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CUSTOM MANUFACTURED IN THE USA BY RADIO SHACK H A DIVISION OF TANDY CORPORATION 



The FCC Wants You to Know . . . 

This equipment generates and uses radio frequency energy. If not installed and used prop- 
erly, that is, in strict accordance with the manufacturer's instructions, it may cause interfer- 
ence to radio and television reception. 

It has been type tested and found to comply with the limits for a Class B computing 
device in accordance with the specifications in Subpart J of Part 15 of FCC Rules, which are 
designed to provide reasonable protection against such interference in a residential instal- 
lation. However, there is no guarantee that interference will not occur in a particular 
installation. 

If this equipment does cause interference to radio or television reception, which can be 
determined by turning the equipment off and on, the user is encouraged to try to correct the 
interference by one or more of the following measures: 

• Reorient the receiving antenna 

• Relocate the computer with respect to the receiver 

• Move the computer away from the receiver 

• Plug the computer into a different outlet so that computer and receiver are on different 
branch circuits. 

If necessary, you should consult the dealer or an experienced radio/television technician for 
additional suggestions. You may find the following booklet prepared by the Federal Com- 
munications Commission helpful: How to Identify and Resolve Radio-TV Interference 
Problems. 

This booklet is available from the US Government Printing Office, Washington, DC 
20402, Stock No. 004-000-00345-4. 



Warning 



This equipment has been certified to comply with the limits for a Class B computing device, 
pursuant to Subpart J of Part 15 of FCC Rules. Only peripherals (computer input/output 
devices, terminals, printers, etc.) certified to comply with the Class B limits may be attached 
to this computer. Operation with non-certified peripherals is likely to result in interference to 
radio and TV reception. 
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INSTRUCTIONS FOR USE 



1 . Register one software package per card only. 

2. Complete the Software Registration portion of this form and mail it immediately. 
The Catalog No. may be found by examining the upper-right corner of your diskette. 

3. For convenience a change of address card has been included. Copy all information 
from the Registration Card onto it prior to sending the Registration Card. 



Computer Merchandising 

P.O. Box 2910 

Fort Worth, Texas 761 1 3-291 

Attn : Software Registration 
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Model III Users 

XFERSYS UTILITY ON TRSDOS 1.3 

The Model III diskette in this package contains a NEW 
version of TRSDOS which is not compatible with OLD versions 
of TRSDOS. 

OLD TRSDOS diskettes to be used under the NEW TRSDOS MUST 
be XFERSYSed before use. Once XFERSYSed, an OLD TRSDOS 
diskette becomes a NEW TRSDOS diskette and should not be 
used with OLD TRSDOS again. If you started with an OLD 
system or data diskette, the XFERSYSed diskette will be a 
NEW system or data diskette respectively. 

OLD diskettes used under NEW TRSDOS without XFERSYSing, may 
cause extraneous information to be read at the end of 
files, giving a false End-of-File (EOF) indication. Some 
programs will not function properly under these conditions. 

NEW diskettes used under OLD TRSDOS, may not access all 
data and/or NEW programs may not run correctly. 

If you need to use the XFERSYS utility, see the TRSDOS 
section of your TRS-80 Model III Disk System Owner's 
Manual. 

Note: When changing from one TRSDOS to the other, you MUST 
press the RESET button each time the diskette in 
Drive is changed. You may also XFERSYS onto a NEW 
data disk. If this is done, all system files of the 
system diskette will be moved onto the data diskette. 

RADIO SHACK APPLICATION PROGRAMS WHICH WERE DELIVERED ON AN 
OLD TRSDOS DISKETTE SHOULD NOT BE XFERSYSed. 



OLD: TRSDOS 1.1 and 1.2. 

NEW: TRSDOS 1.3 

file: A collection of information stored as one 

named unit in the directory. 
program: A file which causes the computer to 

perform a function. 
data: Information contained in a file which is 

used by a program. 
system diskette: A diskette containing TRSDOS. When this 

diskette is placed in Drive and the 

RESET button is pressed, TRSDOS will begin 

to run. 
data diskette: A diskette which does not contain TRSDOS. 

If this diskette is placed in Drive and 

RESET is pressed, the screen will clear 

and "Not a SYSTEM Disk" will be displayed. 
XFERSYS: A program contained on the TRSDOS 1.3 

diskette. 
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Tips On Loading Disk basic 

There are several ways, other than those described in the manual, to start up Disk basic. 

basic program -F.files -m: address 

program is a trsdos file specification for a Disk basic program. After start-up, Disk basic will run the 
program. This is optional. 

-f: files tells Disk basic the maximum number of files that may be open at one time, files is a 
number from to 15. This is optional; if omitted, 3 is used. If Variable length files are 
needed, you must include the suffix v after files; otherwise, files will be Fixed length. 

-w.address tells Disk basic not to use memory above the specified address. This is optional; if 
omitted, Disk basic uses all memory up to Top. 

If all options are omitted, Disk basic will prompt with HON MANY FILES? and MEMORY? 

The options allow you to specify any or all of the following: 

• A program to run after Disk basic is started. 

• The maximum number of data files that may be Open at one time. The larger the number of files, 
the less area available for storing and executing your programs. (Note: Each Fixed length file takes 
up 360 bytes and each Variable length file takes up 616 bytes of memory.) 

• The highest address to be used by Disk basic during program execution. Omit this unless you are 
going to call machine-language subroutines. 

Examples , f s 

Under trsdos ready, if you type: 

BASIC fENTER j , Disk basic will enter the command mode once you answer the files and 
memory prompts. 

BASIC - F : 1 ( INTER ]. Disk basic will Open one fixed length file and protect no memory. 

BASIC -M : 32000 CENTER ), Disk basic will Open three fixed length files and will use 
memory no higher than 32000. 



BASIC PAYROLL -F:3M . OTTER ), Disk basic will start-up, then load and run the basic 
program called payroll; three variable length files can be Opened, and basic can use all 
available memory. 

Note: If you PATCH Disk basic to prompt you for cassette speed when you enter Disk basic, you 
will still be prompted with CASS' no matter which option you use. 

Important Note for Model III trsdos 1.3 Users! 

The 1.3 version of trsdos will return with ERROR 31 (PROGRAM NOT FOUND) when you 
attempt to use the ROUTE command. 

Thank-You! 

Radio /hack 

I A Division of Tandy Corporation - 
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zation by Tandy Corporation is strictly prohibited. 
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To Our Customers 



Congratulations on your purchase of the Model III Disk System. We think it's a 
valuable tool which will save you work as well as give you hours of enjoyment 
(or maybe both at once). You'll have all the power of the non-disk Model III, 
plus the following features: 

• Your Computer can now be controlled by trsdos™ , the powerful trs-80 Disk 
Operating System, trsdos is included on a diskette with the Disk System. 

• Using trsdos, you can run a wide variety of programs, such as the Disk basic 
interpreter included on the trsdos diskette. 

a Each "system" diskette has approximately 126,720 bytes of storage available 
for your own programs and data; each "data" diskette has 178,944 bytes 
available. 

8 You can load and save data at the approximate rate of 250,000 bits per second. 

• Your system can continue to grow in power and convenience. When Radio 
Shack issues improvements and enhancements to the system programs, you 
can "install" them simply by obtaining a new release of the trsdos diskette. 

Model III Manuals 

Publications related to the use of the Model III Disk System: 

1 . Model III Disk System Owner's Manual (this manual). We'll call it the "Disk 
Manual" for short. 

2. Model 111 Disk System Quick Reference Card. 

3. Model III Operation and basic Language Reference Manual, the "Model III 
Manual" for short. 

4. Model HI basic Quick Reference Card. 

For Disk Operation: 

This Disk Manual supplements the Model III Manual. Use the Disk Manual as 
the primary source of information; we'll tell you when to refer to the non-disk 
Model III Manual . 

For Non-Disk Operation: 

To use the Computer as a non-disk system, all you need is the Model III 
Manual. 

For Programming Information: 

The Model III Manual contains most of the programming information, except 
that which pertains to disk input/output. In this manual, we will assume that you 
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are familiar with the basic programming definitions and details given in the 
Model III Manual. 



About This Manual 

The Model III Disk System is intended for use by novices as well as 
experienced computer operators and programmers. In designing and writing this 
Disk Manual, we've tried to define and satisfy the needs of both groups: 

- Novices who might prefer a sequential presentation which emphasizes 
procedures and explains the purpose of various features. 

• Experienced users who might prefer a more analytical presentation which 
makes it easy to find specific information. 

In this manual, you'll find information that should satisfy your needs, whichever 
group you might belong to. 

The "Sample Sessions" are especially geared for novices, while the Technical 
Information chapters are for the more experienced users. 

Keep in mind, however, that it isn't necessary to read the entire manual to 
operate the Disk System, if you are only interested in Disk basic, for example, 
read the Operation section of this book and then turn directly to the Disk basic 
section. You can then go back to the trsdos section when you need to. 

Special Terms 

Even in the non-technical sections of this manual, we've had to use numerous 
special terms. Rather than scattering and repeating definitions throughout the 
book, we have used the following convention which we hope you'll find 
helpful. 

Special terms which are fully defined in another part of the manual are printed in 
boldface. Look up the word or phrase in the Index; this will tell you where the 
word is fully defined. 
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Installation 



First set up the Computer according to the instructions in the Model III Manual. 

If you have a one- or two-drive system, installation is now complete. The built- 
in drives should be ready for use. 

If you have a three- or four-drive system, you need to connect the external 
drives. 



External Disk Drives 

The two external drives are not interchangeable. They have different Radio 
Shack Catalog Numbers and a few internal differences. 



System 
Name 



Catalog 
Number 



First External Drive Purchased 
(Includes Cable) 

Second External Drive Purchased 



"Drive 2/3" 26-1164 



"Drive 2' 



26- 



The 26-1 164 drive may be used as Drive 2 or 3, depending on the number of 
drives in the system. In a three-drive system, it is always Drive 2 (the last 
drive). In a four-drive system, it is always Drive 3 (again, the last drive). 

The 26-1 161 drive may only be used in a four-drive system, in which it must be 
Drive 2. 

1 . Locate the flat "ribbon" cable that was included with the 26-1 164 drive. 
Notice that it has a single plug on one end, and two plugs clustered at the 
other end. See Figure 1 for plug labels. 

2. Connect the solitary "Computer" plug to the Disk Expansion Jack on the 
bottom rear of the Computer. See Figure 2. 

3. Now refer to Figure 3. Connect the external drive(s) to the other end of the 
cable, as follows: 

3-A. If you have one external drive (26-1 164): 

Connect it to the "Drive 2" plug near the middle of the ribbon cable. 

3-B. If you have two external drives (26-1 164 and 26-1 161): 

Connect the 26-1 164 to the "Drive 3" plug on the end of the cable. 
Connect the 26-1 161 to the "Drive 2" plug near the middle of the cable. 

4. Plug the external drive(s) into an appropriate source of ac power. Power 
requirements are specified on the unit and in the specifications given in this 
manual. 

You are now ready to start the Disk System. 
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Computer Plug 



Drive 3 Plug 




Figure 1. External Disk Cable with Plugs Labeled. 




Figure 2. Connection of the External Disk Cable to the Model III. 
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MINI-DISK (REAR VIEW) 



Attach the plug so the cable exits 
toward the rear of the Computer. 



EDGE CARD PLUGS 




GUIDE PIN 



Figure 3. Connection of external disk drives. 
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Operation 



First, take a few minutes to become familiar with the various elements of your 
Disk System. Refer to Figures 4 and 5. This is very important. If you try to use 
the Computer without having a little background information, you could damage 
a diskette. 




Figure 4. The Model 111 Disk System with External Drives (optional/extra). 



CD Drive 0. The trsdos "system diskette" goes 
in this drive. 

© Drives 1, 2, and 3. These drives may 
contain "data diskettes." Data diskettes are 
described briefly in this chapter. 

© Drive Select led. When a drive is being 
accessed, its led lights up. 

© Drive Door. To insert or remove a diskette, 
open this door. Never remove a diskette 
while the led is lit, or while the diskette 
contains open files. 



© Reset Button. When you press this button, 
the Computer will attempt to load the 
operating system software from Drive 0. The 
trsdos diskette should be in Drive when 
you press this button. 

© Power Switch. All drives should be empty 
when you turn the Computer on or off. 
Otherwise, the information on the diskettes 
could be destroyed. 




Figure 5. A Diskette. (Catalog Number 26-305, 26-405, or 26-406) 



© Storage Envelope. While a diskette is not in 
use, keep it here. 

© Write Protect Notch. When this is covered, 
the disk-drives cannot write (change infor- 
mation) on the diskette. Do not pinch the tab 
into the notch when you apply it. If the tab 
becomes indented, the disk drive may not 
sense that the disk is write-protected. Leave 
the notch uncovered if you want to save or 
change information on the diskette. 

© Jacket. The diskette is permanently sealed 
inside this protective jacket. Do not attempt 
to remove it. 



© Read/Write Window. The disk drive 
accesses the diskette surface through this 
window. Don't touch the diskette surface. 

© Label. To write on this label, use only a felt- 
tipped pen. Any other writing implement 
might damage the diskette. 



Diskettes 



In general, handle diskettes carefully, using the same precautions you use with 
tape cassettes and high-fidelity records. A small indentation, dust particle, or 
scratch can render all or part of a diskette unreadable — permanently. 

• Keep the diskette in its storage envelope whenever it is not in one of the 
drives. 

• Do not place a diskette in the drive while you are turning the system on or off. 

• Keep diskettes away from magnetic fields (transformers, AC motors, magnets, 
tvs, radios, etc.). Strong magnetic fields will erase data stored on a diskette. 
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• Handle diskettes by the jacket only. Do not touch any of the exposed surfaces. 
Don't try to wipe or clean the diskette surface; it scratches easily. 

• Keep diskettes out of direct sunlight and away from heat. 

• Avoid contamination of diskettes with cigarette ashes, dust or other particles. 

• Do not write directly on the diskette jacket with a hard point device such as a 
ball point pen or lead pencil; use a felt tip pen only. 

• Store diskettes in a vertical file folder on a shelf where they are protected from 
pressure to their sides (just as phono records are stored). 

• In very dusty environments, you may need to provide filtered air to the 
computer room. 

Tips on Labeling Diskettes 

Each diskette has a permanent label on its jacket. This label is for "vital 
statistics" that will never change. For example, to help keep track of diskettes. 
it's a good idea to assign a unique number to each diskette. Write such a number 
on the permanent label. You might also put your name on the diskette, and 
record the date when the diskette was first put into use. Remember, use only a 
felt tip pen for marking. 

This "permanent" label is not a good place to record the contents of the diskette 
since that will change, and you don't want to be erasing or scratching out 
information from this label. 



System Start-Up 



1. Turn all peripherals on. 

2. Turn the Computer on. Wait until all disk drive motors stop. 

3. Locate the trsdos diskette that was supplied with the Disk System. Insert it 
into Drive 0, with the label side facing up and the read/write window 
pointing into the drive slot. See Figure 6. 

4. When the diskette is fully inserted, close the drive door. 

5. Press reset. The Computer should now load trsdos and begin the start-up 
dialog described in the next section. 

If nothing happens on the Display, or if the message: DISKETTE? or NOT A 
SYSTEM DISK is displayed, check the following: 

• Are you using a trsdos "system" diskette? 

• Is the diskette properly inserted into Drive 0? 

• If external drives are present, are they properly connected and turned on? 
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Figure 6. Inserting a Diskette. 

If you can't find the problem, refer to the Troubleshooting and Maintenance 
chapter for further suggestions. 

TRSDOS Start-Up Dialog 

Whenever you reset the Model III Disk System, it loads trsdos and begins the 
start-up dialog. 

1 . The trsdos version number and date of creation will be displayed, followed 
by the amount of ram <32K or 48K) and the number of drives in the system. 

2. trsdos will prompt you to enter the date in the form mm/dd <yy. For example, 
07/04/80 for July 4, 1980. Type in the correct date and press CENTEB). trsdos 
will not continue until you type in the date correctly. 

3. trsdos will prompt you to enter the time in 24-hour form HH:MM:SS. For 
example, 14:45:00 for 2:45 p.m. Type in the correct time and press ClMIiB). If 
you don't wish to set the time, simply press (ENTER ) at the beginning of the 
line, trsdos will set the time to 00:00:00. 

4. trsdos will now display the message, TRSDOS READY 

Whenever this is displayed, you are in the trsdos ready mode, and you may 
type in a trsdos command. 
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Important Disk Operations 

In this section we will describe three very important operations: 

1 . Duplicating the trsdos diskette (backup) 

2. Initializing a data diskette (format) 

3. Converting files from Model I to Model III trsdos (convert). 

All new customers should complete the trsdos backup procedure now; multi- 
drive customers should also complete the format operation for a few diskettes. 
Detailed information is provided later in this manual; here we will simply 
outline the procedures. 

Making a BACKUP (Duplicate) of TRSDOS 

Your first operation should be to duplicate the trsdos diskette you received 
from Radio Shack. The trsdos diskette contains a utility program called 
backup to accomplish this. 

1 . Locate the trsdos diskette and a new, blank diskette. The trsdos diskette 
will be referred to as the "source," while the blank one will be called the 
"destination," during backup. 

2. Start trsdos as explained in the previous section. TRSDOS READY should be 
displayed. 

3. Type: BACKUP (ENTER) 

4. trsdos will now load and start backup. It will ask you: 
SOURCE DRIVE NUMBER? 

Specify the drive which contains the original trsdos diskette by typing: 



(ENTER) 

5. Next trsdos will ask: DESTINATION DRIVE NUMBER? 

Now specify the drive which will be used for making the duplicate trsdos. If 
you have two or more drives in your system, type: 1 (ENTER) 

6. trsdos will ask: SOURCE DISK MASTER PASSWORD? 



Type: PASSWORD (ENTER) 

(password is the password of the supplied diskette.) 

7. Now'the duplication process will begin. 

If the destination diskette is not formatted, backup will format it before 
continuing. (Before any diskette can be used, it must be initialized or 
"formatted" — the data regions defined and labeled, and a table of contents 
or "directory" created.) 
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If you are using a single-drive system, trsdos will prompt you to swap 
source and destination diskettes several times during the formatting/backup 
process. 

After a single-drive backup, trsdos will display the message: 



INSERT SYSTEM DISKETTE CENTER) 



Be sure you have a trsdos diskette in Drive 0, then press (EMIiB). 

The duplication process is now complete. We suggest you save the original 
trsdos and use the duplicate as your working copy. If anything happens to the 
working copy, you can make another one from the original. 

Making a Data Diskette (FORMAT) 

This section applies to multi-drive systems only. 

Drive must always contain a trsdos diskette, so the Computer can have 
access to the system programs stored there. Much of the storage capacity of this 
diskette is taken up by the system programs. 

However, the other drives in the system may contain "data" diskettes which 
have no system programs. All of the storage capacity of such diskettes is 
available for your programs and data. 

The format utility program takes a diskette and initializes or "formats" it. 
If the diskette was previously formatted, all prior information can be lost. 
The resultant diskette contains no system files and may only be used in 
Drive 1 , 2 or 3 . 



1 . In the trsdos ready mode, type: FORMAT (ENTER ) 

2. trsdos will start the formatter program and ask you a series of questions: 

FORMAT WHICH DRIYE? 



Insert a blank diskette into Drive 1 . Type: 1 ( pTEH ) 

DISKETTE NAME? 

This name will serve as an internal label for the diskette. Type in any 
appropriate name of one to eight letters and numbers, starting with a letter. 
Press CENTER) at the end of the name. 

MASTER PASSWORD? 

The password may be from one to eight letters and numbers, starting with a 
letter. Press CENTER) at the end of the password. 

Use of the password allows backup, prot, and purge access to all non- 
system files. Unless special protection is needed, we suggest you use the 
password password. Whatever password you select, don't forget it! 



r "II 

> Ji 



TRS-80 MODEL HI DISK SYSTEM 



If the diskette contains data, trsdos will warn you: 

DISKETTE CONTAINS DATA, USE DISK OR NOT'' 

The warning is needed since format erases all previous information from the 
diskette. Type N (ENTER) to cancel format; type Y ( ENTER) or U (ENTER) to 
continue it. 

3. trsdos will now format and verify the diskette. The data diskette will then 
be ready for use in Drive 1, 2, or 3. 

Model I/III Conversion (CONVERT) 

In general, Model I trsdos diskettes cannot be used in a Model III Disk 
System. However, Model III trsdos includes a special program, convert, to 
read a Model I trsdos diskette and copy its non-system files onto a Model III 
trsdos diskette. 

In two-drive systems, the files must be copied onto a Model 111 system diskette; 
in three- or four-drive systems, the files may be copied onto a data diskette. 

Here are abbreviated instructions for using this program. For further details, see 
convert. 

1. Using a Model I Disk System, remove all passwords from the diskette to be 
converted. You can do this with the prot command, described in the Model I 
TRSDOSlDisk basic Owner's Manual. 

2. Start Model III trsdos. 

3. Place the Model I diskette in Drive 1 , 2 or 3. (In two-drive systems, use 
Drive 1; in three- or four-drive systems. Drive 2.) 

4. In three- or four-drive systems, place a Model III data diskette in Drive 1 . 



5. Type: CONVERT (ENTER) 

4. The conversion program will start by asking for the source drive number. 
Type in the number of the drive containing the Model 1 diskette, then press 
CENTER) . 

5. Next, the conversion program will ask for the destination drive number. Type 
in the number of the drive containing the Model III diskette, then press 
(ENTER) . (In two-drive systems, use Drive 0; in three- or four-drive systems, 
Drive 1.) 

6. Now all the non-system files will be converted and copied onto the 
destination diskette. As each file is copied, its name will be displayed. 

7. When the process is completed, you may remove the Model I diskette. It is 
unchanged by the convert program. The destination diskette contains the 
converted files. 

8. To restore password protection to the converted files, you may use the prot 
or attrib command. 
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Disk BASIC 

Quick Instructions for Using Disk BASIC 

In this section we'll "walk you" through the following procedures: 

1 . Starting Disk basic 

2. Running a simple program 

3. Saving a program in a disk file 

4. Loading a program from a disk file 

For programming information, see the Disk basic section of this manual. 
Here we are showing procedures only. 

Starting Disk BASIC 

Under trsdos ready, type: BASIC CENTER) 

The Computer will load and start basic. First, it will ask two questions. 
Press (ENTER) in response to each of them. 

HON MANY FILES? (ENTER) 
MEMORY SIZE? (ENTER) 

A heading will be displayed, followed by: 

READY 

You may now begin using Disk basic. 

Saving a Program 

You should have a program in memory, and be in Basic's ready mode. Type: 
SAVE "PROGRAM" (ENTER) 

basic should now save the program in a disk file we arbitrarily named 
"program." Any other suitable file name would do. 

Loading a Program 

For this sample session, we will load the program just saved. 

First type: NEW CENTER") to erase it from memory. (This is to prove that it can be 
retrieved from the disk file.) 
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Now type: LOAD " PROGRAM" (MM) and basic will load the specified 
program. 

You may now list it and run it. 

For further information on using Disk basic, see Section 3 of this manual. 

Setting the Cassette Baud Rate under Disk 

BASIC 

trsdos sets the cassette baud rate to High. If you would like to change this, use 
the following trsdos command: 

PATCH BASIC/CMD ( ADD=5202 »FIND=00 >CHG=FF) (ENTER) 

Consequently, you will be prompted with: CASS? whenever you start Disk 
basic. 

You may then type either H (High) or L (Low) to choose the rate you need. 

To change the system diskette back to its original state (i.e., no CASS?), simply 
use the trsdos patch command again but reverse the find and chg values. 
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Troubleshooting and Maintenance 

If you have problems operating your Model III Disk System, please check the 
following symptoms and cures, and check the corresponding table in your 
Model ill Manual. 

If you can't solve the problem, take the unit to your local Radio Shack. We'll 
have it fixed and returned to you as soon as possible. 



Symptom 


Cure 


Disk drive motors run 
continuously when the Computer 
is turned on. 


Check external drive connection sequence. 
Drive 26-1 1 64 must always be the last 
external drive. 


Computer will not load trsdos. 


1 . Make sure you have inserted the 
trsdos diskette properly in Drive 0. 

2. Make sure all peripherals are properly 
connected. 


Error Messages 


Look up the message in the trsdos or 
basic Error Message Section. The "cure" 
should be listed. 


Frequent disk i/o errors 


1 . Diskette is partially erased. Backup the 
diskette, then re-format it. 

2. Diskette is worn out. Use backup copy, if 
available, to make a new working copy. 

3. Disk drives need cleaning or alignment 
by Radio Shack service technicians. 



Maintenance 

For reliable operation, the disk drives must be kept clean and properly aligned. 
These procedures should be done by Radio Shack service technicians, according 
to the following schedule: 



Degree of Use 

Commercial data processing 
environment 

Occasional home use 



Maintenance Interval 
Every month for medium use. 

Every 8-10 months; more often if 
needed. 



For further instructions, see the Troubleshooting and Maintenance section in 
your Model III Manual. 
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Notation and Abbreviations 

For the sake of clarity and brevity, we've used some special notation and type 
styles in this book. 

capitals and punctuation 

indicate material which must be entered exactly as it appears. (The only 
punctuation symbols not entered are ellipses, explained below.) For example, 
in the line: 

DUMP LISTER (START = 7000,END = 7100,TRA = 7004) 

every letter and character should be typed as indicated. 

lowercase italics 

represent words, letters, characters or values you supply from a set of acceptable 
values for a particular command. For example, the line: 

LIST filename 

indicates that you can supply any valid file specification after list. 



Ellipsis indicates that the preceding items can be repeated. For example: 
ATTRIB filename (option, . , ,) 

indicates that several options may be repeated inside the parentheses. 



This special symbol is used occasionally to indicate a blank-space character 
(ASCII code 32 decimal, 20 hexadecimal). 

PRINT "DHBIB!" 

X'nnnn" 

Indicates that nnnn is a hexadecimal number. All other numbers in the text 
of this book are in decimal form, unless otherwise noted. 

X'7000' 

indicates the hexadecimal value 7000 (decimal 28672). 

COMPUTER TYPE 

Any words, letters, or numbers that are displayed on the screen will be in 
computer type (dot-matrix). Uppercase letters are used; however, your screen at 
times may display lowercase letters instead. 
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Specifications 



Diskettes 



Diskette Organization 
(Formatted Diskette) 



Operating Temperature 

Power Requirements 
(Externa! Drives) 



5Va mini-diskettes 
Radio Shack Catalog 
Number 26-305, 
26-405 (package of three), 
or 26-406 (package of 10) 

Single-sided 

Double-density 

40 Tracks 

18 Sectors/Track 

256 Bytes/Sector 

55 to 80 Degrees Fahrenheit 
13 to 27 Degrees Celsius 

120 VAC, 60 Hz, 28 VA (240 VAC, 
Hz, Australian; 220 VAC. 50 Hz, 
European) 



50 
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Description of TRSDOS 



What Is TRSDOS? 

trsdos (pronounced "triss-doss") stands for "trs-80 Disk Operating System.' 
It fulfills three roles: 

1 . Master Program 

2. Command Interpreter 

3 . Program Manager 

As the master program, trsdos enables the microprocessor and its various 
components to interact efficiently. The components include: 

• Random Access Memory (ram), trsdos reserves space for its own needs and 
allocates space for user programs. 

• Disk Drives, trsdos interfaces with the disk hardware and provides a file 
system for storing system and user data on diskettes. 

• Input/output devices. These include the keyboard, video display, printer, and 
rs-232~c equipment. 

trsdos is also a command interpreter. Whenever it displays TRSDOS READY, 
you may enter commands that control how the system works. These are known 
as "library" commands. 

In its role as program manager, trsdos will load and run system or user 
programs. During this time, the system or user program is in control of the 
Computer. 

Figure 7 illustrates the relationships between these three roles. 



Where Does BASIC Fit In? 

Referring to Figure 7, you'll see that Disk basic falls under the "language 
package" category. 

Disk basic consists of some general enhancements to Model III basic, plus the 
disk input/output capability. It uses Model III basic (stored in rom) whenever 
possible. For instance, the Model III basic rom includes all of the mathematical 
functions. 

If you're used to the non-disk system, there's one difference you should 
understand from the beginning: In the non-disk system, basic is in control when 
you start-up. In the disk system, however, trsdos is in control when you start- 
up. You have to tell trsdos to load and run basic. Only then can you begin 
running a program written in basic. 
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How TRSDOS Uses MAM 

trsdos is stored on the system diskette included with your Disk System. Each 
time the Computer is turned on or reset, the trsdos master program is loaded 
into ram so it can take charge. 

trsdos occupies approximately 40,000 bytes of space on the diskette; however, 
only a portion of that is in ram at once. This is possible because trsdos is 
divided into several independent "modules." 

The "resident" module is in memory at all times. It consists of input/output 
drivers, tables, the command interpreter, and other essential routines. 

Additional modules are loaded as needed, and replaced (or "overlaid") by other 
modules when they are no longer needed. 

Note: After you enter a library or utility command, you will usually hear 
trsdos accessing the system disk. It is loading an overlay module which 
contains the code necessary to complete the command. 

The Memory Map in Figure 8 illustrates how trsdos utilizes the available 
memory space. 



Command 
Interpreter 



Master Program 



System Utility 
Programs (FORMAT, 
BACKUP, etc.) 



Figure 7. trsdos Roles. 



Program Manager 



TRSDOS 



Language packages 


Z-80 


(Disk BASIC, 


User 


Editor/Assembler, 


Programs 


etc.) 






BASIC, 

OTHER 

PROGRAMS 



ROM 



TRSDOS 



DEBUG 



"DO" 



Figure 8. trsdos Memory Map 
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4000H 

5200H 
5500H 
DOS OVERLAYS 

7000H 

FORMAT 
8000H 



END- 180H 



(32K) (48K) 

END (BFFFH) (FFFFH) 
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Entering a Command 

Whenever the trsdos prompt, 

TRSDOS READY 

is displayed, you can type in a command, which can be no more than 63 
characters in length. You must press (ENTER) to end the line, trsdos will then 
"accept" the command. 

For example, type: CLS CENTER) trsdos will clear the Display and the trsdos 
ready prompt will reappear. 

In general, your commands will require more than one word. For example, to 
kill (delete) a file named myname, you have to specify the command and the 
filename. 



KILL MYNAME (ENTER) 

tells trsdos to find the file named myname, eliminate it from the diskette, and 
release the space previously occupied by that file. 

Whenever you type in a line, trsdos follows this procedure: 

1 . First it checks to see if what you've typed is the name of a trsdos command. 
If it is, trsdos executes it immediately. 

2. If what you typed is not a trsdos command, then trsdos will check to see if 
it's the name of a program file on one of the drives. 

3. When searching for a file, trsdos looks first through Drive 0, then Drive 1, 
etc., unless you include an particular drive specification with the file name 
— or specify the master command (see Library Commands). 

If trsdos finds a specified user file, it will load and execute the file if it is a 
program file. Otherwise, you'll get an error message. 



Command Syntax 



Command syntax is a command's general form (like the grammar or structure of 
an English sentence). The syntax tells how to use keywords (such as dir, list, 
create, etc.) together with the necessary parameters and punctuation. 

If you need help remembering the syntax form of a specific command while 
you're operating trsdos, type in: 



HELP command (ENTER) 
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command should be the specific Library Command you're having trouble with. 
trsdos will give you the syntax format as well as a brief definition of the 
command. 



Commands (Syntax Forms) 

No-file commands 



command (siirisris} cummsni 

options Is a %&'. site «r m&ra psrginetsrs tim may be iiBBded by the 
command. Same RLmms^s hg VS ?m options. The parentheses 
ground cpuons must ba imluAii unless the &ptio»s Itself is 

eoflimeans an Gnosis! fteiri usee in mzamenx the purpose of the 
command. Comment:; are useful inside automatic command 
input files (sea buub mi m). 



One-file commands 



sornmsnd filename {options} ssmmenf 

fifsiisms 18 a standard vrsms ills ssecsfhjation. 
ojitims - Sse dellnlvion sfiovs 
Gunmen!- -88e dBfinhion atiove. 



| :;.x.^-.-tA^-Jl-!»».-l 
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Two-file commands 



command filename delimiter filename (options) comment 
filename is 3 standard irsijos file specification. 
delimiter is a blank space 
options — See definition above 
comment— See definition above. 



File Specification 

The only way to store information on a diskette is to put it in a disk file. 
Afterwards, that information can be retrieved via the file name you gave the file 
when you created or renamed it. 

A file specification has the general form: 



filename ext. password :d 

filename consists of a letter followed by up to seven optional letters 
or numbers. 

ext is an optional name-extension: ext is a sequence of up to three 
letters or numbers, starting with a letter. 

password is an optional password; password is a sequence of up to 
eight letters or numbers, starting with a letter. 

rfis an optional disk-drive specification, d is one of the digits 
n i o -* 



Note: There can be no blank spaces inside a file specification, trsdos 
terminates the file specification at the first blank space. 

For example: F I LEA/ TXT, MANAGER: 3 references the file named filea/txt 
with the password manager, on Drive 3. 






TRSDO! 



The name, extension, and drive-specification all contribute to the uniqueness of 
a file specification. The password does not. It simply controls access to the file. 

File Names 

A file name consists of a name and an optional name extension. For the name, 
you can choose any letter, followed by up to seven additional numbers or letters. 
To use a name extension, start with a diagonal slash / and add no more than 
three numbers or letters; however, the first character must be a letter. 

For example: 

MODEL3/TXT INVENTORY DATA11/BAS 

NAMES/A 12 AUGUST/ A 15 WAREHOUS 

TEST TEST1 TEST 1 /A 

are all valid and distinct file names. 

Although name extensions are optional, they are useful for identifying what type 
of data is in the file. For example, you might want to use the following set of 
extensions: 

/BAS for basic program 

/TXT for asco text 

/CMD for machine-language command file 

/DAT for data 

One advantage of using extensions is that you can tell by just looking at the 
directory what kind of information a file contains. 

Another advantage is that trsdos can recognize certain extensions. For 
example, if a file has the extension /cmd, the trsdos will load and attempt to 
execute that file when you type: filename (ENTER) omitting the extension /cmd. 




Drive Specification 



If you give trsdos a command such as: K ILL TEST/ A trsdos will search for 
the file test/a first in Drive 0, then in Drive 1, 2, and finally in Drive 3 until it 
finds the file. 

Anytime you omit a drive-specification, trsdos will follow this sequence, 
unless you use the master command. 

It is possible to tell trsdos exactly which drive you want to use by specifying 
the drive. A drive specification consists of a colon followed by one of the digits 
0,1,2, or 3, corresponding to one of the four drives you might be using. 

For example: KILL TEST/ A: 3 tells trsdos delete the file test/a on Drive 3 
only. 



23 



' — \m 

iS-BO MODEL 111 DISK SYSTEM 
'mmmt^t ' ----- 



Anytime trsdos has to open a file (e.g., to list it for you), it will follow the 
same sequence. When trsdos has to write a file, it will skip over any write- 
protected diskettes. 

Password 

You can protect a file from unauthorized access and use by assigning passwords 
to the file. That way, a person cannot gain access to a file without using the 
appropriate password. 

It's important to realize that every file has a password, even if you didn't specify 
it when the file was created. In such instances, the password becomes eight 
blank spaces. In this case, the file becomes unprotected — anyone can gain total 
access simply by referring to the filename. 

trsdos allows you to assign two passwords to a file: 

• An "Update word," which grants total access to the information 

• An "Access word," which grants limited access to the information (see 

ATTRIB) 

When you create a file, the Update and Access words are both set equal to the 
password you specify. You can change them later with the attrib command. 

A password consists of a period followed by one to eight letters or numbers. If 
you do not assign a password to a file, trsdos uses a default password of eight 
blanks. 

For example, suppose you have a file named secret/bas. and the file has 
myname as an update and access word. Then the command: KILL SECRETS/ 
BAS will not cause the file to be killed. You must include the password myname 
in the file specification. 

Suppose a file is named domain/bas and has blanks for the password. Then the 
command: KILL DOMAIN/BAS, GUESS will not be obeyed, since guess is not 
the password. 

A Few Important Definitions 

System vs. Data Diskettes 

A system diskette is one which contains the trsdos disk operating system 
software. Subject to space limitations, it may also contain your own files. A 
system diskette must always be in Drive while the Computer is in use. 

A data diskette, on the other hand, does not contain the operating system 
software, and therefore cannot be used in Drive 0. It may be used in Drive 1 , 2 
or 3. Such a diskette has a maximum of space available for storing your own 
programs and data. 
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System, Program, and Data Files 

System files include the trsdos operating system software, the basic language 
interpreter, the format, backup and convert utilities, and other software 
which is released by Radio Shack. These files appear in the Directory with an 
"S" attribute. (See dir) 

Program files are stored in a special format which allows them to be loaded and 
executed directly from the trsdos ready level. For example, the basic 
interpreter is a program file. 

Data files include all files that are not in the correct format to allow loading and 
executing from trsdos ready. For example, a program written in basic will be 
stored as a data file. It can be loaded and executed from basic, but not from 
trsdos ready. 

Master Passwords 

Each diskette is initially assigned a master password during format or backup. 
(Your master password for trsdos is password.) The master password allows 
you to use backup, purge, and prot on a diskette. Using a diskette's master 
password, you may change it (see prot). 



DOs j^ -J 
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TRSDOS Library Commands 



APPEND 
Append files 



append source-file destination-file 

source-file is the specification for the file which is to be 
copied onto the end of the other file 

destination-file is the specification for the fiie which is to 
receive the appendage (addition). 

Note: Both source- and destination-files must be in ascii 
format (data files or basic programs saved with the a 
option). 



append copies the contents of the source-file onto the end of the destination-file. 
The source-file is unaffected, while the destination-file is extended to include the 
source-file. 

Note: The logical record lengths must match. See dir for more information on 
logical record lengths. 

Examples 

APPEND WORDFILE/C WORDFILE/D 

A copy of wordfile/c is appended to wordfile/d. 

APPEND REGI0N1/DAT TOTAL/DAT, GUESS 

A copy of region i/D at is appended to total/dat, which is protected with the 
password guess. 

Sample Uses 

Suppose you have two data files, payroll/a and payroll/b. 
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PAYROLL/A 



PAYROLL/B 



At Kins i W.Ri . 
Baker. J.B. .. 
Chambers » C.P. 
D o d s o n » M . W . » 
Kickawon > T » Y . 



Lewis* G . E * 
Miller* L , , 
Petersons B. 
R o d r i 3 y e z * F 



You can combine the two files with the command: 

APPEND PAYROLL/B PAYROLL/A 

payroll/a will now look like this: 

PAYROLL/A 

Atkins * W,R. . 
Baker* J.B. .» 
Chambers * C.P. 
D o d s o n » M . W » * 
Kickamon * T . Y . 
Lewis* G . E . . . 
M i 1 1 e r * L , . . 
Peterson* B. . 
Rodriguez* F . 

payroll/b will be unaffected. To see the APPENDed file, type LIST PAYROLL/A 
(ASCII). 

Note: Do not load a program under basic after an append. 



ATTRIB 

Change a File's Password 



attr!6 fiis (mmiiivMz =- : nsnw.wn - name,"m\ - level) 
//7e is il(8 file specification. 

visibility must be i or n. Tells trsdos whether the tile is Invisible (i) or 

•••..•:■ :-:-^ : :\-r <, :Vr-- :- : " - ^ r>-:. -yvh^-i)- '■: ■■.■■.z^i'c?^ 

-o. -■ 'v~* '.-::■.': -. : <yr.:y- ■■-:■- ?.<)z?.iz v ?."j s v'~l\im. '.»'•?■ fu^s-: *o=< : 
is unchanged. If acc-~ . is userL the access word h set to 

.-- • -- :Y'; .- :.-■.• •.-> ■ ;.; ■.:■?. :..-?;■.; v. ::•:• •- --'.v. ;1?:. '■■.- ; ;^?;s •■;■-::■?. 
Is unchanged, if wu ~ , is usetf, the update word h set to 
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ppin - /five/tsiSs TRSiins the protection level for access. II omitted. 
in Mat is usiLhanyeii 

Level Degree cf access granted by access word 

•.•in Fuii access, no protector 

Kiu K;i!. rsnams. rsari. execute, and write (gives 

iotai access, i.e., the least-protected}. 

nawi Rename, read execute, and write 

WHSTt Read execute, ana write 

rfai) Paso ans sxet'^e. 

rxn: ?ye;^ie sni'v 

Nc ! .8' Each !evBi si'nws access ic MseM plus ail lower levels 



attrib lets you change the passwords to an existing file or makes the file 
invisible or non-invisible. Passwords are initially assigned when the file is 
created. At that time, the update and access words are set to the same value 
(either the password you specified or a blank password). 

Examples 

ATTRIB DATAFILE ( I *ACC = JULY14 »UPD=M0USE »PR0T=READ ) 

Makes the file invisible, sets the access password to julyh and the update 
password to mouse. Use of the access word will allow only reading and 
executing the file. 

ATTRIB PAYROLL/BAS, SECRET (N»ACC=») 

Sets the access word to blanks. The file is made non-invisible and the protection 
level assigned to the update word is left unchanged. 

ATTRIB OLD/DAT, APPLES (UPD= f ) 
Sets the update word to blanks. 

ATTRIB PAYROLL/BAS, PW (PR0T=EXEC) 

Leaves the access and update words unchanged, but changes the level of access. 

Sample Uses 

Suppose you have a data file, payroll, and you want an employee to use the 
file in preparing paychecks. You want the employee to be able to read the file 
but not to change it. Then use a command like: 
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ATTRIB PAYROLL (I »ACC=PAYDAY »UPD=AMOCADO »PROT=READ ) 

Now tell the clerk to use the password payday (which allows read only); while 
only you know the password, avocado, which grants total access to the file. 

Protecting BASIC Programs 

You may give a basic program execute-only protection using the attrib 
command. For example, suppose the program is named test (no password). 
Under trsdos ready, execute this command: 

ATTRIB TEST < ACC= »UPD=UALLEY »PR0T=EXEC> 

Now test has a blank access password, an update password of valley, and an 
access level of execute only. Without using the update password, there is now 
only one way to execute the program: 

1. Start basic. 

2. Type: RUN "TEST" 

(This is the only way to access the program. If the operator attempts to load 
it instead, basic will erase the program from memory before returning with 

READY.) 

After the run "test" command, basic will load and execute the program. If 
the operator presses (BBEM) or if the program ends normally, basic will erase the 
program before returning with the ready message. This makes it impossible to 
obtain a listing of the program — unless the update password is used. 

Of course, if you use the update password, you may gain full access to the 
program. 



AUTO 

Automatic Command after System Start-up 



Aijio com ma nd* ling 

sommsm-llm gives trsbos a mmm&m m Vm name of an esesutable 
program tile orealac! sy build. 

n csmmand-iine is given, ths mmmnm ml m sxeouted m reset/ 

if command-line is oml'isti, the prswioys auto mmmmi Is srsssd 
from the diskette. 
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This command lets you provide a command to be executed whenever trsdos is 
started (power-up or reset). You can use it to get a desired program running 
without any operator action required, except for typing in the date and time. 

When you enter an auto command, trsdos writes command-line into its start- 
up procedure, trsdos does not check for valid commands; if the command line 
contains an error, it will be detected the next time the System is started up. 

Examples 

AUTO DIR (SYS) 

Tells trsdos to execute the command dir (sys) after the start-up procedure. 
Each time the System is reset or powered up, it will automatically execute that 
command after you enter the date and time. 

AUTO BASIC 

Tells trsdos to load and execute basic each time the System is started up. 

AUTO FORMS (WIDTH=80) 

Tells trsdos to reset the printer width parameter each time the System is started 
up. 

AUTO PAYROLL/ CMD 

Tells trsdos to load and execute payroll/cmd (must be a machine-language 
program) after each System start-up. 

AUTO DO STARTER 

Tells trsdos to take automatic key-ins from the file named starter after each 
System start-up. See build and do. 

To Erase an AUTO Command 

Type: AUTO (ENTER) 

This tells trsdos to erase any automatic command. The command will be 
deleted the next time you power-up or reset the System. 

The acknowledgement: AUTO = " " is displayed after an erasure. 

To Override an AUTO Command 

You can bypass any automatic command by holding down (ENTER) while pressing 
reset. You must continue holding down (ENTER) until you are prompted for the 
date during the initialization process. 
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BUILD 

Create an Automatic Command Input File 



build file 

file is a file specification which cannot include an extension. 



This command lets you create an automatic command input file which can be 
executed via the do command. The file must contain data that would normally 
be typed in from the keyboard to the trsdos ready mode. 

build files are intended for passing command lines to trsdos just as if they'd 
been typed in at the trsdos ready level. Note: clear cannot be used in a do 
file. 

When you enter the build command, build creates the file and immediately 
prompts you to begin inserting lines. Each time you complete a line, press 
(ENTER) . (While typing in a line, you can use the usual cursor control keys for 
erasures and corrections.) 

To end the build file, simply press (BREAK) at the beginning of a line. 

First type: BUILD filename 

You will then be prompted to type in the command text. You then type in up to 
63 characters, then press (ENTER) . You may enter as many lines as necessary. 
Press (BREAK ) to quit and return to trsdos ready. 

A Sample BUILD-FIle 

Here's a hypothetical suiLD-file that initializes the serial interface and the printer 
driver: 

SETCOH (BAUD=1200»WAIT) 

FORMS (WIDTH=80) 

PAUSE SERIAL INTERFACE & PRINTER INITIALIZED 



m?m 



31 






CLEAR 

Clear User Memory 



clear { stabt -■ aaaa.aiB ~ tbb'OMfW. ~ cccs) 

is a four-dloit hexstieeSma! number from soon to fhs end of user 

! .:*-.j ■■--■£££ S":-.-:l ■'«■■:■:;■ ■.:■ r-*i: - :-.?:. ;vv ■ '• •:; -•.. ::';-:1 .v.- .;:.;.; 
!i 5 ;c!i? .; : i:'*;/5 ; ':f:ji: :;,.':..■ .v.m: -.v-m -- ; ; <.■■/. 

used, start = aaea mus! aim fee used 

mem = cccc sets tns memory protect sdaress. cccc is a four-digit 
hexadecimal number from mm fa ffff. if ihis option is omitted. 



This command gets you off to a fresh start. 

Depending on the options you select, this command will: 

• Zero user memory (load binary zero into each memory address above 6000) 

• Clear the Display 

• Un-protect all memory 

See Memory Requirements of trsdos for more information on the memory- 
protect address. Note: clear cannot be used in a do file. 

Example 

CLEAR (START=90EB)END=0A000) 

Note: Hexadecimal numbers which begin with a letter must be prefaced by zero 
(see above example). 

CLEAR <HEM=7000) 
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CLOCK 

Turn On Clock Display 



clock {switch) 

switch gives irsdos one of two options, on or off. 
If option is omitted, irsdos uses on. 



This command controls the real-time clock display in the upper right corner of 
the Video Display. When it is on, the 24-hour time will be displayed and 
updated once each second, regardless of what program is executing. 

Clock display is off at trsdos start-up. 

Note: Except during cassette and disk i/o, the real-time clock is always running, 

regardless of whether the clock display is on. 

Examples 

CLOCK 

Turns on the clock display. 

CLOCK (OFF) 

Turns the clock display off. 

See time and date. 

CLS 

Clear the Screen 



CLS 



This command clears the Display and puts it in the 64 character/line mode. 

Example 

CLS 
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COPY 

Copy a File or Files 



Three io-Kn>. 

A) copy scares-?;!;: zesuAE'io;- *7 : 5 

source-Hie is a ilia spec-iicafion ?or the tMs is be oociee 

destination-file Is a tiie siisciflcatian sot 'he nsme ?nd o-ivs -^ me 
duplicate fiis 

B) copy source-tile .d 

source-file is 1f3flr.ec aiv-r»p 

■tf tells irscoc to copy the ;';:; w\z 2> : v* :?. ;^h<; ;!•- iS.t^ fj 1 - ::£^ 

lllllllSll^^ 

w.'is ? "wird card" ?j!f, *?p?jsst:^^v;;;^ -i- 'AVii'jK *r.-? ?: i ■:'•;■:.■■•.•= ;s 
Glutted sr:i: :N csjens-on Is glvs^ :r u;o; -vi:? ?>:,':■■■ z'.-\ :l _-i 
which have 2 ^a^niny f sisrrijo;?. !-sg?5r-iilev- ;•■ :tz h : ^ ::>v;. -. 

:rfis deilnsD above 



This command copies source-file into the new file defined by destination-file. 
This allows you to copy a file from one disk to another, using a single drive if 
necessary. (In the latter case, you must include drive specifications in both file 
specifications.) For single-drive systems (Drive 0), both diskettes must contain 
trsdos. (i.e., Data diskettes aren't allowed in Drive 0.) 

Examples 

COPY OLDFILE/BAS NEWFILE/BAS 

Copies oldfile/bas into a new file named newfile/bas. trsdos will search 
through all drives for oldfile/bas, and will copy it onto the first disk which is 
not write -protected . 

COPY NAMEFILE/TXT :1 

This command specifies a file named namefile/txt to another disk. 
COPY FILE/EXT :0 : i 

This command copies file/ext from Drive to Drive 1 . 
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COPY /BAS:0 :1 

tells trsdos to copy all Drive files which have the extension /bas. The files 
will be copied onto Drive 1, using their present file names and extensions. 

Sample Use 

Whenever a file is updated, use copy to make a backup file on another disk. You 
can also use copy to restructure a file for faster access. Be sure the destination 
disk is already less segmented than the source disk; otherwise the new file could 
be more segmented than the old one. (See free for information on file 
segmentation.) 

To rename a file on the same disk, use rename, not copy. 



CREATE 

Create a Pre-allocated File 



c p f a t t fi<fn^:r^ :',rl ■-■ aaa.HM:-- hhh) 

iiies.&v.s is the tile specification. 

; ?-. - Ma is the logical rpcoid length aaa is a decimal number 
between /.era anc ;&& !? omitted. 255 is assumed 

Hi i biih Is ?h3 fiu:* : ci of records to allow for hbb is the number 0! 
reiUi'as ; ; --;'!:: ; i- sm^ted no rer,n»is are aiiccsts^ 



This command lets you create a file and pre-allocate (set aside) space for its 
future contents. This is different from the default (normal) trsdos procedure in 
which space is allocated to a file dynamically, i.e., as necessary when data is 
written into the file. 

If you open the file for sequential writes, trsdos will de-allocate (recover) any 
unused granules when the file is closed. If you open the file for random access, 
trsdos will not de-allocate space when the file is closed. 
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You may want to use create to prepare a file which will contain a known 
amount of data. This will usually speed up file write operations. File reading 
will also be faster, since pre-allocated files are less segmented or dispersed on 
the disk — requiring less motion of the read/write mechanism to locate the 
records. 

Examples 

CREATE DATAFILE/BAS (REC=300, LRL=0) 

Creates a file named datafile/bas, and allocates space for 300 256-byte 
records. 

CREATE NAMES/TXT, IRIS (LRL=64 »REC=50) 

Creates a file named names/txt protected by the password iris. The file will be 
large enough to contain 50 records, each 64 bytes long. 

CREATE PAYROLL/BAS 

Creates a file named payroll/bas but allocates no space to it. 

Sample Use 

Suppose you are going to store personnel information on no more than 250 
employees, and each data record will look like this: 

Name (Up to 25 letters) 

Social Security Number (11 characters) 

Job Description (Up to 92 characters) 

Then your records would need to be 25 + 1 i + 92 = 128 bytes long. 

You could create an appropriate file with this command: 

CREATE PERSONNL/TXT ( REC=250 »LRL= 128 ) 

Once created, this pre-allocated file would allow faster writing than would a 
dynamically allocated file, since trsdos would not have to stop writing 
periodically to allocate more space (unless you exceed the pre-allocated 
amount). 

DATE 

Reset or Get Today's Date 



)ah mm da yy 

mm rid yy is the specification tor (he month [mm), day \rid] and 
vea? ! W- 
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Each must be a two-digit decimal number between the following 

: > '{: vf 'I04M^ : ^X : ::: '::>} rt. K'^>' ^:'V , |^^^rlt'^??i• 
used, they a!! must Be yseo. 
;. ^;-i. ••:,■ ;-.- : ■.;::v-;- •-•• : ..:..: ; ;:-\^V : - "•'■ ■'•■•^•. — " 
I! mm.-tidyy is given, trsdos resets the dafe. 



This command lets you reset the date or display the date. 

You initially set the date when trsdos is started up. After that, trsdos updates 
the date automatically, using its built-in calendar. You can enter any two-digit 
year after 1900. 

When you request the date, trsdos displays it in the format: 07/25/80 for July 
25, 1980. 

Examples 

DATE 

Displays the current date. 

DATE 07/18/80 

Resets the date to July 18, 1980. 



DEBUG 

Start Debug Monitor 



This command starts the debug monitor, which allows you to enter, test, and 
debug machine-language programs. 



mm 
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Its features include: 

• Full- or half-screen displays of memory contents 

• Commands for modifications to ram and register contents 

• Single-step execution of programs 

• Breakpoint interruption of program execution 

• Transfer of control (Jump) 

• "Editing" of disk-files 

debug uses the memory area from x'4E00' to X'54FF' (see trsdos Memory 
Map), debug can only be used on programs in the user area x'550(r to top. 

Examples 

DEBUG 

Turns debug on. Press 2D to quit debugging and return to trsdos. 



Turns debug off. 

Command Description 

Debug commands are usually entered by pressing a single key. In most cases, 
you do not have to press (ENTER) after the command has been typed in. Either 
a prompt will immediately be displayed or debug will execute the operation 
without further instruction. 

In some cases, you will have to enter a specific hexadecimal value or address 
(see R and j commands, for instance). Instead of pressing (ENTER) after the 
address is typed in, you will have to press (SPACEBAR ). 

Once you have entered the debug program, you may use any of the following 
special commands: 

D (Display Memory Contents) 

Press © to display the contents of memory, trsdos will respond with the 
prompt: D ADDRESS = You should type in the hexadecimal address of the 
memory location you wish to see. 

The display will be either half- or full-screen, depending on the format you are 
currently using (see below). 
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X (Half-Screen Display) 

Press ® to put the Display in the half-screen format. A 128-byte block 01 
memory will be displayed starting with the next lowest address which is a factor 
of 16. 

Figure 9 shows a typical half-screen format. 

S (Full-Screen Display) 

Press © to display the contents of a 256-byte block of memory starting with the 
next lowest address which is a factor of 256. 

Note: The last 16 bytes on the Display will be overlaid by any command line 
typed in after the full-screen display is updated. 

M (Modify RAM) 

Press CD to change to the disk utility display format (see the f command). 
trsdos will respond with the prompt: M ADDRESS = You should type in the 
four-digit hexadecimal address of the memory location you wish to modify, 
followed by a blank space (anything other than a space will abort the 
command). 

The display will change to the memory edit format. The cursor will appear as a 
blinking character at the specified location. 

To exit the modify mode, press CENTER) to keep all changes made. 

R (Change Register Contents) 

Type: 



Raa.WftA ■spacebar; 

btsbb is ins lOb-iiiQii r^scSe*:;:!!*?! »s;^s w'ikh -a;!! bt iosf-f? -uiu ~z 
H \f v.-8i- than foui ajgits s>e tysjes:- \n Derosa pressing s^rES/^ 
leading zeros are assumed. 



I (Instruction Singie-Step) 

Pressing CD will allow the Computer to execute a single z-80 instruction. The 
display will then be updated. 
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Start address 
of one 16-byte 
"row" of RAM 



RAM display — 
( hex contents 
' of each byte 



ASCii display 

(• indicates a 

nondisplayable 

character) 




Z-80 register contents ' 
Op-code Instructions at the "PC" address 



Figure 9. Half-Screen Format. 



The instruction in the memory contents referenced by the program counter is 
executed. The program counter is increased by the appropriate value, and the 
control is returned to debug. 

debug will not, however, step through a call or jump into a rom address. 



C (Call Single-Step) 

If you wish to complete an entire call/return sequence, press ©. The call is 
then executed and control is returned to debug when the subroutine returns. 
Otherwise, this instruction acts just like the i command. 

You will not be able to step through a call or jump into a rom address, 

U (Update) 

Pressing 3D causes the Display to be updated repeatedly. Press any key to exit 
from this mode. 



/ 
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; (Increment Display Address) 

If the Display is half-screen, the first location shown is incremented by 16 when 
you press CD- If the full-screen format is displayed, the starting address will be 
incremented by 256. 

— (Decrement Display Address) 

If the Display is half-screen, the first location is decremented by 16 when you 
press (ED. If the full-screen format is displayed, the starting address will be 
decremented by 256. 

J (Jump) 

Press GD to transfer control to a machine-language program, setting optional 
breakpoints. 

Debug will respond with the prompt: J ADDRESS? = 

You may type in a jump address and a breakpoint address. The command is 
terminated when you press (ENTER) . Type in the addresses in one of three 
formats: 



j address? - aaaa,bbbb\MfW 
j address? = aaaa iMTlFP 
j address? = ,bbbb(&tTM 

aaaa is a four-digit hexadecimal address specifying the jump 
destination. If omitted, the address in the pc register is used 

bbbb is a four-digit hexadecimal address specifying a breakpoint. 
Before the Computer executes an instruction at this address, it 
will return control to debug. If this address Is omitted, control 
will not return to debug. 



Notes: Breakpoints must be set at the beginning of z-80 instructions. You may 
not set breakpoints in rom addresses. The breakpointed address will contain an 
X'F7' until the breakpoint is encountered. Then the original contents will be 
restored and debug will take control again. 

Q (Quit) 

Pressing © turns off debug and returns control to trsdos. 
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F (File Patch Utility) 

This command lets you load and modify the contents of a diskette file. 

When you press ©, debug will respond with the prompt: FILESPEC?. Enter the 
name of the file to be patched. 

debug will set up a full-screen display showing the first 256 bytes in the file. 
You can "page" through the file using the CD and (ED keys. 

Figure 10 gives a typical display. 

In this file-display mode, both hexadecimal and ascii are given for each byte, if 
a code has no displayable character, a period is shown in the ascii area. 

The display control commands are like those for the normal file-display mode: 
CD Next page 
(—) Previous page 

To change the file contents, press fl). This puts you in a modify-memory mode 
like the one previously described. Use the arrow keys to position the cursor (a 
blinking character), then type in the correct contents as a hexadecimal value. 
When you are through changing a page on the display, press (ENTER) . The 
diskette file will be updated and you will be returned to the file-display mode. 

To cancel changes made, do not press CENTER) , press (BREAK) . This will put you 
back in the file-display mode without updating the diskette file. You may press 
CD then CD to restore the page display to its actual contents. 

To quit patching a file, press (BREAK) while in the file display mode, debug will 
prompt you for a new file specification. Press ( BREM) again and you will be 
returned to trsdos ready. 
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Drive # Record # 



Byte Offset 
within Record 



Hexadecimal Contents of 
Each Byte 



if [ 

•CeSSET.ttSK'.aj 

ASCII Translation 



^Igr-deta&aaaaj 



7 







Figure 10. Full-Screen Format 
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DIR 

List the Diskette Directory 



DIR :rf(lNV,SYS,PRT) 

|t-,v hsl? ^:- !!:'-;s;oi!5 u?p; Jjtss -^ "r-HSsfi. n-- ipv^i^p user flies *:>e 

svs lisis sysierc ?*o ;jss> vMes .' ?i;rs*?iefi. r,r?;v non j^visl^'e !i.ser f^??s sir 

fllll^^ 

on the Video Display only. 



This command gives you information about a disk and the files it contains. 

To pause the listing, press (WD. To continue, press (ENTER) . To terminate the 
listing, press (BREAK) . 

Examples 

DIR 

Displays the directory of non-invisible user files in Drive 0. 

DIR si (PRT) 

Lists the directory of the user files in Drive 1 to the Printer. 



Sample Directory Listing 

(See Figure 11.) 

Definition of column headings 



© File Name — The name and extension assigned to a file when it was created. 
The password (if any) is not shown. 

© Attributes — A four-character field. 

The first character is either i (Invisible) or N (Non-invisible). 

The second character is s (System) or * (User) file. 

The third character gives the password protection status: 
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111 



Figure 11. Directory Listing. 

x The file is unprotected (no password). 
a The file has an access word but no update word, 
u The file has an update word but no access word. 
B The file has both update and access words. 
The fourth character specifies the level of access assigned to the access word: 

Total access 

1 Kill file and everything listed below. 

2 Rename file and everything listed beiow. 

3 This designation is not used. 

4 Write and everything listed below. 

5 Read and everything listed below. 

6 Execute only. 

7 No access. 

© Number of Free Granules — How many free granules remain oe the diskette. 

© Logical Record Length — Assigned when the file was created. 

© Number of Records — How many logical records have been written. 

© Number of Granules — How many granules have been used in that 
particular file. 
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® Number of Extents — How many segments (contiguous blocks of up to 32 
granules) of disk space are allocated to the file. 

® End of File (eof) — Shows the last byte number of the file. 

® Creation Date — When the file was created. 

DO 

Begin Auto Command Input from a BUILD-FIie 



illlllllllll^^ 



This command reads and executes the lines stored in a special-format file 
created with the build command. The System executes the commands just as if 
they had been typed in from the Keyboard. 

Command lines in a build file may include library commands or file 
specifications for user programs. 

When do reaches the end of the automatic command input file, it returns control 

to TRSDOS. 

The debug and clear command cannot be included in a build file. 

In addition to executing trsdos library commands, you can load and execute 
user programs from a DO-file. You will probably want to make your program 
name be the last line in the Do-file. 

Examples 

DO STARTER 

trsdos will begin automatic command input from starter, after the operator 
answers the Date and Time prompts. 

AUTO DO STARTER 

Whenever you start trsdos, it will begin automatic command input 
from STARTER. 
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Sample Uses 

Suppose you want to set up the following trsdos functions automatically 
on start-up: 

FORMS (WIDTH=80) 
CLOCK (ON) 

Then use build to create such a file. If you called it begin, then use the 
command: AUTO DO BEGIN to perform the commands each time trsdos 
starts up. 

Note: Files created by DO sometimes lose characters if you try to use more than one 
BASIC statement (such as RUN, SAVE, LOAD, etc.) in the same DO file. 

DUAL 

Duplicate Output to Video and Printer 



DUAL \SWiiCh) 

switch is one of two op/lions. <.rn or off I'' sirmfel m?z^ v- : ie-$ 



This command duplicates all video output to the Printer, and vice versa. It takes 
effect immediately. 

Notes: 

1 . Video and printer output may be different because of intrinsic differences 
between output devices and output software. 

2. Using the dual command will slow down the video output process. 

3. The dual command cannot be used during route and vice versa. 

4. The printer should be ready when you execute the command. 

Sample Use 

For a printed copy of all system/operator dialog, type: DUAL ( ENTER ) 
To turn off the dual process, type: DUAL ( OFF ) fENTER) 
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DUMP 

Store a Program Into a Disk Fie 



dump tils (start - ssaasm ■■--- bbb&.wt. •-■ cscc.m it - matl) 

tils is the Hit speeifiegtsen 

star; = 33aa is the star! aisdress yJ memory siock. aasa must he 3 four 
digit hexadecimal mober greater than oi equal to xvooe. 

i no - Bbhb \% the mi adrirss* y{ lbs memory block. ftMi? musS Be s four- 
dig!! hexadecimal nuniasr. 

ira - ttffc is the \mmm samms where ^ncmm sieris when the pregjam 
is loaded, recr ma si he a iouMiigi! hejtsd&ciasa! number if this 
option is omitted, the uemmand will deiauli to trsdos re-entry. 

rei o = tfsrftf is the start sdcrnss tor ? slscpaing ejj- loading the prcgrsm back 
into memory, tfrfrfrf must bs a four-digit hexadecimal number, i! this 
option is osnlitel m rmmt\m will take place. 

Note: Addresses must be hexadecimal farm . without the x notation 

'■'■'.■;; •;-•..£ fd:;: ? ;• ?;:;. ".: ••.•: ?<y ;•,?,:. yyy:,; »■;;;.:•,-, ns^s ■ w : ti- ; ? 



This command copies a machine-language program from memory into a 
program file. You can then load and execute the program at any time by entering 
the file name in the trsdos ready mode. 

Examples 

DUHP LISTER (START=7000 *END=7100 »TRA=7004 > 

Creates a program file named lister/cmd containing the program in memory 
locations x'7000' to x'7ioo\ When loaded, lister/cmd will occupy the same 
addresses, and trsdos will protect memory beginning at X'70oo\ The program is 

executable for the trsdos ready mode. 

DUMP PR0G2 (START=7000>END=7F00»TRA=8010»RELO=8000) 

Creates a program file named prog2/cmd containing the program in addresses 
x-7000- to X-7F00-. When loaded, progi/cmd will reside from X'soocr to x'8Foo\ 
Execution will start at x'soio". 
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ERROR 

Display Error Message 



error number 

number is a seeing number mi t -asses srrzt iOQc. 



This command displays a descriptive error message. For example, after 
receiving the message, * * ERROR 47 * * you may respond with the 
command: ERROR 47 (EMTER) and trsdos will display the full error message. 

For a complete list of error codes and messages, see the Technical Information 
section of this manual. 

FORMS 

Set Printer Parameters 



FORMS (W!DJH=W, liNfc'S- !) 

width = wis the maximum number oS characters pe? bumi tine, s! & ih>e 
reaches this ienglh. irsdcs will htseri a carriage rftlurn ^c isreg a new 
line !J this option ;s offliitea. !ha yuMeni maxi:^m v^e-i?; evil; be 
used. To disable the tnaximusr. hrse iddih tefeiL-rs. Lis v,^-h = i&5 
irsdos wii! no; force new sires 

lsnfs - / is tiia riiimesr c; liisss ;:&: .•-•? ys. T asLi.;£ *kss 'it 5 ; 5i -vs ^de 
However, sasic wi!i use i\ ;-\ cerrpuUnj *to r.scssssry p&p 
displacement for execuiior: a? :! -.PR>^r QiRsni) cs sxeuiiiao s? iskcS ••- / 
is omitted, the current vs;us Is yseti 



This command lets you modify the printer forms control features of trsdos. 
The default values are: 

Maximum line width: 132 

Lines/page: 60 

forms also sets the line count to 0. 

The FORMS command WIDTH option will print two extra characters. For instance, if 
you specify FORMS (WIDTH = 80), TRSDOS will print 82 characters per line . If 
the LINES = option is used , there is no automatic form feed . If you do not specify 
LINES = , the default value is not 60; TRSDOS will use the current value. 



TRSDOS LJj 
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Examples 

If you are using 8'/2"-wide forms, you will probably want to set width = 80: 
FORMS (WIDTH=80) 

If you are using 14"-long forms, you may want to set lines = 78. 
FORMS (LINES=78) 

This change will allow the basic statement, lprintchr$(12), to advance a page 
by the correct number of lines. 

Notes: 

1. The width you specify is stored in ram location 16427. The lines you 
specify is stored in ram location 16424. 

2. The Printer must be ready when you execute this command. 



FREE 

Display Disk Allocation Map 



FREE .rflPRTI 

:ti is the drive specification. I? omiiiee. Bnve T: a «eo 
(PRT) teils trsdos to send the rsiap to the Crimps 

If omitted, trsdos sends the snap to ihc Vidso l^sa'av ori 



This command gives you a map of granule allocation on a diskette. (A granule, 
1280 bytes, is the unit of space allocation.) It also shows the location of the 
directory and any flawed sectors. 

When a diskette has been used extensively (file updates, files killed, extended, 
etc.), files often become segmented (dispersed or fragmented). This slows the 
access time, since the disk read/write mechanism must move back and forth 
across the diskette to read and write to a file. 

free helps you determine just how segmented your disk files are. If you decide 
you'd like to re-organize a particular file to allow faster access, you can then 
copy it onto a relatively "clean" diskette. 
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Examples 

FREE 

Displays a free space map of the diskette in Drive 0. 

FREE (PRT) 

Lists the free space for Drive to the Printer. 

FREE :1 (PRT) 

Lists the Drive 1 map to the Printer. 

A Typical FREE Display 

Four special symbols are used in the free map. 
• Unused Granule 

Direct Directory Information 
X Allocated Granule 

Flawed Granule Contains a Flawed Sector (Unusable) 

A typical free map display is shown in Figure 12. 



Disk Name 



All six granyles in 
track 2 are allocated 




Figure 12. Free Map. 



The directory is located 
on track 17. 



HELP 
Explanation 



Command 



•-».■• ';:.;■'-:;.:" 



available subjects. 
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Example 

If you type in the following: HELP BACKUP [ENTER) trsdos will respond with 
the syntax format, a definition of the command, and an explanation of 
the abbreviation. 

HELP SYNTAX tells trsdos to explain the help descriptions. 



Ji\.J.JL<JL< 

Delete a File or Group of Files 



Two syntaxes. 



A) Kits, file 

fileis a file specification 

8} Kin extci 

ex? is a file extension thai was/ contain three characters, 
■{/is a drive specification, it musibe provided. 



This command deletes one file or a group of files, depending on which form is 
used. Form A deletes the specified file. If no drive specification is given, 
trsdos deletes the file from the first diskette that contains it. 

Form B deletes all files with a specified extension, regardless of the file name of 
each file. If no drive specification is given, the files will be deleted from the first 
drive that contains a matching file specification. 

Examples 

KILL TESTPROG/BAS 

Deletes the named file from the first drive that contains it. 

KILL JOBFILE/IDY, PASSWORD; 1 

Deletes the named file from Drive 1 . The file has a password of password. 

KILL /BAS;0 

Deletes from Drive all files having the extension bas. 
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LIB 

Display Library Commands 



i!B 



This command lists to the Display all the library commands. For help with a 
command, use help. 

Example 

LIB 



LIST 

List Contents of a Fie 



LIST ///eiPRI. SLOW. ASCI!) 

file is the file specification 

phi tens tbsdos Id Sis! !o ihe Winter If cmittsd. only the Video Display is 

Slow teiis T:>snos w c?u3c brwly 3fi?r each reco^c. If emitted, the listing is 

ASCii tesiS 1RSL).?3 1 5 list '<«£ '>\S Hi i.SV. ti- ?!!!?/, It iWiiltsd. riesadesiira; 

format is used. 



This routine lists the contents of a file. The listing shows both the hexadecimal 
contents and the ascii characters corresponding to each value. For values 
outside the range (X'20\ X'7F'), a period is displayed. 

Use the ascii option for text files and basic programs saved with the a option. 

Note: Only ascii codes X'00'-X'7F' are sent to the Printer. Bit 7 is always 
set to 0. 

During the listing, press (@) to pause, (ENTER) to continue, or (BREAK) to exit. 
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Examples 

LIST DATA/TXT (ASCII) 

Lists the contents of data/txt in ascii format. 

LIST FILE/A (SLOW) 

Lists the contents of file/a, pausing after each record. 

LIST PROGRAM/CMD (PRT) 

Lists the file program/CMD to the Printer. 

LOAD 

Load a Program Fie 



iS*K^^^AlA*tfs|g;;^..^ ' : /°r ; A^:;, : ^ : . ;.,; :l a:a;;.i; a;\a :vAaU-a v\ /.Tt,: 
file vs a im specificeslDn for a \m gjbsIes by the :;u«p cooinva^d. 



This command loads a machine-language program file into memory. After the 
file is loaded, trsdos returns to the trsdos ready mode. 

You cannot use this command to load a basic program or any file created by 
basic. See the basic Reference Manual for instructions on loading basic 
programs. 

Note: The file must load into the user area (X"7000'-topj. 

Examples 

LOAD PAYR0LL/PT1 

Sample Use 

Often several program modules must be loaded into memory for use by a master 
program. For example, suppose payroll/pti and payroll/pt2 are modules, and 
menu is the master program. Then you could use the commands: 

LOAD PAYROLL/ PTi 
LOAD PAYROLL/ PT2 

to get modules into memory, and then type: MENU to load and execute menu. 
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MASTER 

Set Master Mead/Write Br'we 



MASTER (PRiVE-g) 

s is the drive specification, if mnmi Ut'as is ssl m the ?r-as&;* dnvs 



This command allows you to assign a specified drive as the Master Read or 
Write drive in the system. When searching for a file, trsdos will start with the 
master drive. 

If the file is not found on the specified drive, trsdos will continue searching on 
the next higher-numbered drive. 

Example 

After you enter the command: HASTER < DR I ME= 1 ) Drive 1 becomes the 
master drive. 



PATCH 

Change the Contents of a Disk Fie 



patch tile fAsK) -- gaea.vm - Mw,m - ??> 

fise <s the file spenffitatiori 

add - saga specifies the addrsss at which ths asta \u Icmd aass is s four- 
digit bexasteimai numlisr. 

find - bb specifies the string pa mm to find for compart ie). M is a 
hexadscl-mai sequence. 

chs = bc specifies the new eantenfs far ;hs ayi'scst). cc is a ^afiedma! 
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This command lets you make minor corrections in any disk file, provided that: 

1. You know the existing contents and location of the data you want to change. 

2. You want to replace one string of code or data with another string of the 
same length. 

You can use patch to make minor changes to your own machine-language 
programs; you won't have to change the source code, re-assemble it, and re- 
create the file. 

Another application for patch is to allow you to implement any modifications to 
trsdos that may be supplied by Radio Shack. That way, you do not have to 
wait for a later release of the operating system. 

Sample Use 

Suppose you want to change seven bytes in a machine-language program file. 
First determine where the seven-byte sequence resides in ram when the program 
is loaded. Then make sure your replacement string is the same length as that 
of the original string. For example, you might write down the information 
as follows: 

File to be changed: vread 

Start address: x'5280' 

Sequence of code to be changed: x'CD2D25E5' 

Replacement code: x*ooooooo9* 

Then you could use the following command: 

PATCH UREAD ( ADD=5280 *FIND=0CD2D25E5 »CHG=00000009 ) 



PAUSE 

Pause Execution for Operator Action 



pause message 



message is ;ha :r<ssi3$? lo '?■?. >i\viv?.\^-. tii':^ ^t i&i^' : - .^scs^-f:. '.^ 
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This command is intended for use inside a do file so trsdos can print a message 
or reminder. 

To continue after the pause, trsdos prompts you with the message: 

PRESS <ENTER> TO CONTINUE 



Example 

PAUSE INSERT DISKETTE *2i 



trsdos displays pause, next the message and then prompts you to press (ENTER) 
to continue execution. 

PAUSE 

PRESS < ENTER)- TO CONTINUE 



trsdos displays pause and then next prompts you to press (ENTER) to continue. 
See build and do for sample uses. 



PROT 

Use or Change a Diskette's Master Password 



:tfis an optional drive specification. If omitted. Drive is used 

pw tells trsoos you want to change the master password. 

lock tells trsdos to assign the master password tc eil unprotected ass 
files. If omitted, the unprotected tiles remain unprotected 



prot lets you use the master password to protect all unprotected files at once, or 
to change the master password. 

The master password will be needed to backup the diskette, so be sure to 
remember it! 

Note: The master password on the trsdos factory-release diskette is password. 
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Examples 

PROT sB (PW) 

Tells trsdos to change the master password on the Drive diskette, trsdos wil 
prompt you first for the old master password, then for the new master password. 

PROT :1 (LOCK) 

Tells trsdos to assign the master password to all unprotected user files, trsdos 
will first prompt you for the master password. 

PURGE 
Delete Files 



hhwi -tf (Hle-type) 

is the drive wrsich contains the disk \u m purged. 
tile-type mu%< be mm of the ioiiowmg-. 

tt ;"•■ :-.-. : £>: - ^ ■■■":■ s =c^! Y;s . :. t;tNt 

. ■".' '- ';-.:'•■• : --- :.-r.\:-^: ::u...-.-\ i^.r-.K^ '■■. .'■_-■ ;■ t- 



This command allows quick deletion of files from a particular diskette. To use 
purge, you must know the diskette's master password, (trsdos System 

diskettes are supplied with the password password.) 

When the command is entered, trsdos will ask for the diskette's password. 
Type in up to eight characters. Press ( ENTER) if you typed fewer than eight 
characters. The System will then display user filenames one at a time, 
prompting you to kill or leave each file. 

Example 

PURGE :1 

trsdos will purge user files from Drive 1 . This would include basic programs. 

PURGE :1 (I NO) 

trsdos will purge all invisible files in Drive 1 . 
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Note: System diskettes contain some files which are not shown in any of the 
directory listings. You may delete these files with a special form of purge: 




pur Gil * :d {file type) 



The asterisk tells trsdos to ask you if you want to delete the System files. If 
you do delete them, the diskette becomes a data diskette and may only be used 
in Drive 1, 2 or 3. 

The other parts of this command are as explained previously. However, be sure 
to do the purge using Drive 1, 2 or 3, since the diskette will become "non- 
system" during the purge. 

RELO 

Change Where Program Loads into Memory 



relo file (ado = aaaa) 

///e is the file specification 

add = aaaa specifies the new load address, aaaa is a four-digit hexadecima. 
number referring to an address in the user memory, aaaa must be in 
the user area of ram. 



This command allows you to change the address at which the program loads into 
memory. It does not change the program itself. 

Note: This command may be useful in conjunction with dump. 

Example 

RELO PROGRAM/CMD (ADD=G578S 

trsdos will load the program program/cmd at the new memory address 
of 6578. 
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RENAME 
Rename a Fie 



Ghiname H ?he svc i\\$ nsr.i. 

newname is the new file name. 

T ^ is!e ngme mg;; isr.tede g 5jr:t»a spsciiioaHc-:: spr» c> password 



This command lets you rename a file or program. Only the name/extension 
is changed; the data in the file and its physical location on the diskette 
are unaffected. 

rename cannot be used to change a file's password protection. Use attrib 
to do that. 

rename also checks to see that the intended new name does not duplicate a 
filename currently on the same diskette. If it does, the command is cancelled 
and an error message is displayed. 

Examples 

RENAME MATHPAK MATHPAK/BA5 

Tells trsdos to add the extension to the filename. 
RENAME ABCDE/DAT ABCDEF/DAT 
Tells trsdos to change the filename only. 
RENAME PAYR0LL1/TXT.GSR PAYR0LL2/TXT 

Tells trsdos to change the filename; the password is retained automatically. 

RENAME FILEi;3 FILE2 

Tells trsdos to change the filename of the file on Drive 3. 
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MOUTE 

Meeting I/O De¥ices 



ROUTE (SOURCE = g8.'X%MH ~ at} 

source = m specifies the source m device. 

■<:■: -'z ,:: ; ..t : • •:•.••"•■ >■■■<■:, :'■ -y-. . :.-yy ■■..va":: '. '*■■■■ t : ';->: ' -j ^T-^r 
abbreviations: 



DO- 


{Display} 


PR 


(Printer) 


KB 


•';-'..v ; ^r,r; ; 


T 


•■'■?.- ^'.- ;«i^::r: 


T/ 


'•^ >:i? ::;m:.:^ 



Sf the source and uESiENAirow options are omitted, trsbos resets vo Drivers 

:;. "::v r ; ;b-'u v ::.:.^ .-.-. ■■..:■• : -uJ \-/-'>i:\:'.- vs •:■:,.-.- : •:..-••' v:^- i;* 
output or both iss input. 



This command allows you to route i/o devices automatically. For example, 
trsdos can route information from the Printer (PR) to the Display (DO) . 

Note: route cannot be used in conjunction with the dual command. 
If you attempt to route data from the Display to the Printer using the ROUTE 
command, characters may be lost or changed. 

Examples 

ROUTE <SOURCE=PR»DESTIN=DO) 

trsdos will route your Printer output to the Display. 

ROUTE 

i/o drivers are returned to their original state. 

For further details on routing i/o see "Routing Input/Output" in the 
Model III Manual. 

Important Note: The 1 .3 version of TRSDOS will return an ERROR 3 1 
(PROGRAM NOT FOUND) when you attempt to use ROUTE. 
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SETCOM 

Set Up RS-232-C Communications 



o: : : i-i:Yii :*e v.: ;: gI". 

word- a is ihe .U'Tiber of bit byte desired, a must be either 5. 6. 7. or 8. 
liSperitilna tr vrn;f needs. !! omitted, the word length is not shanged. 

fm.T/ - 4 specifies the wj$ rale, d must be a decimal number between 50 
and SfiGG it o.milfed the baud ^ate is not changed 

s^o? = <? specifies she -.lumber ot stop bits, c missi be either 1 or 2. if 
winii stop s'li e--- nc* shanged. 

f«r«:y- rf determines whetoei ifie parity is odd. even, or none, dmust be 3 
inorse}. 1 (odd), or 2 (even) It omitted parity is not changed. 

mode type either wait or nowait 

Options -nusi !3fi entered in ihe crrie' shown. 

if ail ihe options are omitted, msnos displays the current rs-23? c settings. 



This command initializes rs-232-c communications via the serial channel. Before 
executing it, you should connect the communications device to the Model III. 

See the Model III Operation Manual for a description of rs-232-c signals used. 

See Using the rs-232-c Interface in the Model III Manual for further details. 

Examples 

SETCOM <WORD = 7»BAUD = 300»STOP=1 »PARITY = 3 .WAIT ) 

This would set the RS-232-c to seven bit words, 300 baud, one stop bit, no parity, 
and place it in the wait mode. 

SETCOM 

The command without specifications will display the current settings. 

The following program will allow you to use your Computer as a terminal. For 
further Information, refer to the Operation section of your Model III Operation 
Manual. 

Note: This program executes at 300 Baud. 

SETCOM is not a serial driver. It is simply a way to change the default parameters of 

theRS-232-C. 
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\'^Wss$ft& \ 



hSS^SSfS^^-'' 



'CHARACTER INPUT BUFFER 
'CHARACTER OUTPUT BUFFER 



5 DEFINT A-Z 'INTEGER VARIABLE FOR SPEED 

10 POKE 16890J 'DON'T WAIT FOR SERIAL I/O 

15 POKE 1(3888, (5*16)+5 'TX/RCV AT BAUD RATE 300 

20 DEFUSRB = &H005A: REM SET UP CALL TO $RSINIT 

40 X = USR0C0) 

G0 DEFUSR1 = &H0050 

65 DEFUSR2 = &H0055 

70 CI = 1S872 

80 CO = 1(3880 

90 ' CHECK FOR SERIAL INPUT 

110 X = USRKB) 'CALL *RSRCO 

120 C* = CHR*(PEEK(CI>) 'LOOK AT INPUT BUFFER 

130 PRINT C$ 'IF C = 0. NOTHING HAPPENS 

140 ' CHECK FOR KEYBOARD INPUT 

150 C* = INKEY* 

'NO KEY, SO GO CHECK SERIAL 

'SELF ECHO 

'PUT CHARACTER INTO OUTPUT BUFFER 

'CALL $RST>( 

'GO CHECK SERIAL INPUT 



1G0 IF C* = "" THEN 110 

1B5 PRINT C*: 

170 POKE CO, ASC(C$) 

190 X = USR2(0) 

200 GOTO 110 



TAPE 

Tape/Disk Transfer 

TAPf (s = source, n = destination) 

source and destination are abbreviations lor the storage devices ?■: 

ISlllSlSlll^^ ••-'"'•• •'•'•'- ^'-/V-V' 

Ifllllll^ ; - 

r Random access memory 

Note: tapf can only be used with machine language pqigran-? ^Ici- 
reside above 5200 hex. if program is below S20G iies 'irs-jus wi : t z\ti 
program storage but not program execution w*x. trDora^s m^;i as 
ciOADedandcsAVFed 



This command transfers z~80 machine-language programs from one storage 
device to another. The following transfers are possible: 

* Tape to disk 



83 



r i«if 

Jut " ri; ^ : __- :7 - ■ ! _ ■ • -"""-_ 



• Disk to tape 

• Tape to ram 

Examples 

TAPE (S=T»D=D) 

Starts a tape-to-disk transfer, trsdos will prompt you CASS?. Select the desired 
baud rate (H for high, L for low), trsdos will then prompt you to press (ENTER) 
when the recorder is ready to play to the Computer. When you press (INTER) , the 
tape will begin loading. 

Note: If no asterisks lash, the recorder volume may need adjustment or the 
baud rate setting may be incorrect. 

trsdos will read the file name from the tape and use that name for the disk file. 
It will copy the program to the first write-enabled diskette, starting with the 
master drive (see master). 

TAPE (S=D*D=T) 

Starts a disk-to-tape transfer, trsdos will prompt you for the desired cassette 
baud rate, then for the diskette file specification. Then it will tell you to press 
(ENTER) when the cassette recorder is ready to record from the Computer. 

TAPE (S=T»D=R) 

Starts a tape-to-RAM transfer, trsdos will prompt you for the cassette baud rate, 
and will tell you to press (ENTER) when the recorder is ready to play to the 
Computer. After loading the program, trsdos will begin execution at the 
transfer address specified on the tape. 



TIME 

Reset or Get tie Time 



time hh:mm:ss 

-'•;: r^n >,-. izz^.-z ,;\ , ;v..: .- '/: ? .- •; •..,■:''--..'. ,:.- 

Each mysf he a two-digit decimal number bemenn the fallowing ranges: 

.% .-• • : J§.\§-23 

jllffstlltli^ 

if hh:mm:ss Is men, trsdos rassts the time. 

II hh:mm:ss is not mm, trsdos displays Ifte ciirrest time. 
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This command lets you reset or display the time. 

Time uses a 24-hour clock. For example, 1:00 P.M. is displayed as 13:00. 

You initially set the time when trsdos is started up. After that, trsdos updates 
the time automatically, using its built-in clock. 

When you request the time, trsdos displays it in this format: i H : 1 5 : 3 1 for 
2:15:31 P.M. 

Examples 

TIME 

Displays the current time. 

TIME 13:20:00 

Resets the time to 1:20:00 P.M. 

Note: If the clock is allowed to run past 23:59:59, it will re-cycle to zero, the 
date will be incremented, and the clock will continue to run. 
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WP 

Write-Protect Via Software 



WP{0fliVE = rf) 



d specifies ihe i'm drive \t \>s proiec-sa. if -.^litfe-l s)i drivsi *ii; ;s 
unprotected. 



Diskettes can be protected from being overwritten by this command. It is a 
software write-protect rather than a hardware write-protect (such as the write- 
protect tab on the diskette). 

Only one drive may be protected at a time. 

To unprotect a drive, making it accessible to writing, simply enter the command 
wp without options or with a different drive ..number specified. The wp command 
will not override a write-protect tab. 
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Examples 

HP (DRIME=i) 

trsdos will write-protect the disk in Drive 1 . 

HP 

trsdos will eliminate write-protection on all drives. 
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TRSDOS Utility Commands 

BACKUP 

Create an Exact Copy of an Original Disk 



backup source destination 

.source specifies the drive containing the original diskette. !< omitted. 
trsdos will prompt you for this information. 

destination specifies the drive containing the diskette to receive the copy. If 
omitted, trsdos will prompt for it. 

source and .destination may reference the same drive. 



backup copies the contents of the source disk to the destination disk. This gives 
you a "safe" copy of the disk. Always keep an extra copy of data or programs 
you have stored on your disks. 

Note: Both source and destination diskettes must be write-enabled. 

trsdos will prompt you at each step after you type; BACKUP 

If you omitted the source/destination-drive numbers, trsdos will begin with the 
prompts: SOURCE DRIVE NUMBER. 

Type in the number of the drive that contains the source diskette and press 

(ENTER) . 

DESTINATION DRIVE NUMBER? 

Type in the number of the drive that will contain the destination diskette and 
press (ENTER) . 

SOURCE DISK MASTER PASSWORD? 

Type in the password assigned to your source diskette. 

DISK CONTAINS DATA > USE DISK OR NOT? 

Type in Y (Yes) or N (No). 

DO YOU WISH TO RE-FORMAT THE DISK? 

Type in Y (Yes) or N (No). 
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If you specified the source/destination drives, trsdos will request the 
password, skipping the first two steps. 

trsdos will then take charge of formatting and verifying the destination disk as 
well as letting you know if there are any errors or flawed tracks. 

CONVERT 

Mode! I to Model III Fie Conversion Utility 



!.0if i»ERT 



Model I formatted diskettes cannot be used in the Model III Disk System. 
However, the convert utility can read a Model I diskette and copy its non- 
system files onto a Model III trsdos diskette. This diskette may then be used 
normally in the Model III Disk System. The original Model I diskette may still 
be used in a Model I Disk System, since it is unchanged by convert. 

convert does not convert or change data; it converts the file storage format. 
For this reason, Model I Disk basic programs may require slight changes before 
they will run properly in the Model III Disk System. Model I machine-language 
programs may require major or minor changes before they will run in the Model 
III Disk System. You may make these changes on the Model I diskette before 
using convert, or on the Model III diskette containing the converted files. 

For example, if you have disks created under Model I TRSDOS 2.3 simply use 
CON v ERT to run the disks under Model III trs DOS 1.3. 

For hints on program conversion, see: 

• Technical Information in this manual 

• Technical Information in the Model III Manual 

• The manual, Instructions for Converting Specified Model I Programs for use 
on trs-80 Model III. 

Drive Usage 

In two-drive systems, the files must be copied onto a Model III system diskette 
in Drive 0; in three- or four-drive systems, the files may be copied onto a data 
diskette in Drive 1, 2 or 3. 

During the conversion process, the Model I diskette is referred to as the 
"source"; the Model III diskette, the "destination." The source diskette cannot 
be in the same drive as that of the destination diskette. 
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Password Protection 

convert is designed to preserve the password security of each file that it 
transfers. To accomplish this and still allow the copying of protected files, 
convert follows different procedures depending on the access and update 
passwords on each file. 

In the simplest case, a file has blank access and update passwords. The copied 
file will be given blank passwords. (If you have a Model I Disk System with 
trsdos 2.3, you may use the prot command to remove all passwords from all 
files. This will simplify the convert process. Do this on the Model I system 
before you attempt to convert to Model III.) 

In another case, the access and passwords are different. If the access password 

Is blank and the update is not, then trsdos will prompt you for the update 
password. If you know the update password, type it In. The file will be copied 
with access and update passwords set to the old update password. If you don't 
know the update password, simply press (ENTER) . The file will be copied with the 
access password set to blanks and the update password set to an unknown value. 

If the access and update passwords are not blank and they are not the same, 
trsdos will not copy the file, but will print the message, FILE SK I PPED, and 
continue with the next file in the source directory. 

Sample Use 

Get the Model I diskette ready. If you have a Model I Disk System with trsdos 
2.3, try to remove all passwords from all your files. This will prevent any 
problems with passwords. The password protection may be restored with the 
Model III ATTRIB or prot commands after the conversion is complete. 

Using the Model III Disk System, you must always have a Model III trsdos 
diskette in Drive 0. trsdos ready should be displayed. Type: CONVERT (ENTER) . 

The program will ask, SOURCE DRIVE?. Type in the number of the drive 
containing the Model I diskette, and press (ENTER) . Then the program will ask, 
DESTINATION DRIVE?. Type in the drive number and press (ENTER) . In two- 
drive systems, you must use Drive as the destination. 

During the conversion process, the name of each file will be displayed as it Is 
copied. If password information is needed, trsdos will prompt you for It. If 
you know the update password, type it in and press (EKTER) . The file will be 
copied and given the same update password. If you do not know the update 
password, simply press (ENTER) , in which case the file will be copied and given 
an unknown update password. 

If a file name on the source diskette is already used on the destination diskette, 
trsdos will print this message: FILE EXISTS, USE IT?. If you type Y, 
trsdos will copy the file. The previous contents of the Model III file will be 
lost. If you type N, trsdos will skip the file, and get the next one from the 
Model I diskette. 
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FORMAT 

Prepare a Data Diskette 



FORMAT Ci 



:d specifies the disk drive which contains the diskette to be formatted. If d 
is omitted, trsdos will prompt you for this information. 



This command lets you prepare data diskettes (either new or disks which contain 
undesired data or programs), leaving a maximum amount of space for your 
program and data files. 

Note: Data diskettes may only be used in Drives 1,2, and 3 except during a 

BACKUP or FORMAT. 

format takes a blank (new or magnetically erased) diskette, records track/sector 
boundaries on it, then initializes it with and creates a directory. 

When format detects a non-blank diskette, it will display a warning message: 

DISK CONTAINS DATA > USE DISK OR NOT? 

Type Y (Yes) and press ( ENTER) if you do want to reformat, N (No) and press 
(ENTER) if you want to save the disk information. 

format will lock out any defective tracks to prevent data from being lost in 
these areas. 

If you begin to get read errors during access, reformat the disk. 

Example 

FORMAT : I 

After you are prompted for DISKETTE NAME? and MASTER PASSWORD?, 
trsdos will format Drive 1 . 
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HERZSO 

Set Up for 50 Hz AC power (non-USA users) 



DO HERZ&O 



starts the utility to change the system for 50 Hz operation hpusg is a sjo- 



This utility is provided for customers in areas where the AC power is 50 rather 
than 60 Hz. It should not be used by any other customers, herzso simply places 
a patch on the diskette that changes the clock speed for 50 Hz users. 

herzso is a DO-file that makes a change in the software of trsdos. Only the 
Drive diskette is changed. Be sure it is write-enabled before you start the De- 
file. Once the herzso change is done, it will remain in effect for that diskette. 

To perform the change, type: 

DO HERZ50 

Once the change has been made, you will need to reset the system to put the 
change into effect. This loads the new software into ram. 

LPC 

Line Printer Control 



tPC 



The lpc utility program allows trsdos to ignore multiple carriage return 
commands. Without lpc, a top-of-form (LPRINTCHR$(12)) command will add an 
extra carriage return/line feed each time it is executed. Also, lpc masks the high 
bit of each data byte, allowing you to send certain intercepted codes to the 
printer. For instance, the basic statement lprintchr$(140) will send code 140- 
128 = 12 (LPRiNT chr$(12» to the Printer. 
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The printers that require lpc are: 

Line Printer III (26-1156) 
Line Printer VI (26-1 loo) 
Daisy Wheel WP50 (26-1157) 
Qume Daisy Wheel (26-1157A) 
Daisy Wheel II (26-1158) 

and all future printers. 

Printers that do not require lpc: 

26-1150, 1152, 1153, 1154, 1159, and the a version of lpiii (26-1 156A). 

You must load the lpc program before you load an application program. The 
easiest way to do this is to copy lpc onto your data/program diskette and then 
use the auto command to load lpc automatically each time you use the system. 
For instance, type: 

COPY LPCsi :0 dNSE) 

Then, to make lpc an auto command on the diskette, type: 

AUTO LPC/CMD (ENTER) 

Whenever you use your program diskette, lpc will automatically load into 
memory and you can use the program as usual. 

lpc locates into the highest available memory. There is no need to set MEMORY 
SIZE to protect lpc. It "hides" itself. However, you still need to set memory if 
required by your application program, lpc will be killed if the clear command 
is used. 

Warning: Once the lpc utility program is loaded and installed, you should not 
reload it except after a reset. Reloading re-installs the program and uses up more 
space each time! lpc will not execute if the Printer has been routed elsewhere. 
Also, if lpc has been executed and then the Printer is routed elsewhere, the 
original printer driver will regain control after the routing. 



MEMTEST 
Test Memory 



MFMUS: 



This program tests your Model Ill's memory (read only and random access). In 
trsdos ready, just type MEMTEST and press (ENTER) . 
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The program automatically tests all memory locations, no matter what memory 
size you have. First it checks read only memory (rom); if everything is okay, it 
automatically goes on and checks random access memory (ram). If all ram 
checks out okay, the program continues. 

If the program detects a rom or ram error, it will display a detailed message. 
Repeat the test to make sure it is a valid error condition. Write the message 
down and contact your nearest Radio Shack for assistance. 

Note: memtest changes the entire contents of ram. Before running it, be sure 
you have saved any valuable code you may have in ram. 

XFERSYS 
Transfer System Fies 



XFERSYS 



xfersys lets you upgrade your version of Model III trsdos by copying all 
system files from a new release diskette (source) onto a previously released 
diskette (destination) (i.e., version 1.2 to version 1.3, etc.). 

System files which already exist on the destination diskette are replaced by those 
from the source diskette. Files which do not exist on the destination diskette are 
added. User files (program and data) are unaffected. 

If you need to run files created under either Model 111 TRSDOS 1 . 1 or 1 .2 with Model 
III TRSDOS 1.3, you must first use the XFERSYS command. An additional feature of 
TRSDOS 1.3 XFERSYS allows you to copy system files (but not operating system 
files) onto a data disk. 

Steps to upgrade a diskette 

Make backup copies of all diskettes to be upgraded. This is an important 
precautionary step. These backup copies should be kept until the upgrading 
process is complete and confirmed. 

Note: Both source and destination diskettes must be write-enabled. 

Insert the new release of trsdos into Drive and press the reset button. Then 
type XFERSYS (ENTER) . 

After the program heading appears, trsdos will prompt you with DISKETTE TO 
CONVERT READY IN DRIVE 1 ( Y / Q )?. Type Y (yes) or (quit) and press 

(HUD. 

The upgrading process will then take place. When the process is complete, 
trsdos will tell you so and take you back to trsdos ready. 

Note: If an error occurs, including your trying to upgrade a non-system diskette, 
the operation will be cancelled and take you back to trsdos ready. 
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Technical Information 



Contents of This Section: 

Disk Organization 

File Structure 

System Routines for Assembly i/o 

Data/Device Control Blocks 

Physical and Logical Records 

Fundamental trsdos i/o Calls 

Additional Routines and Storage Addresses 
trsdos Error Codes/Messages 

Disk Organization 

Each trsdos system diskette contains a trsdos system, a utility command 
library, and a file directory. 

Each diskette is single-sided and has 40 tracks of information. Each track 
contains 18 sectors of 256 bytes each. 

Normally, data read/write operations may be initiated only at sector boundaries, 
and must consist of exactly 256 bytes. However, trsdos allows the user to have 
maximum flexibility with minimal effort by automatically blocking and de- 
blocking all file accesses to user-specified logical record lengths, even if this 
requires "spanning" of two sectors. 

The system disk file structure allows maximum use of disk file space by 
automatically segmenting files across a diskette in several small pieces. These 
pieces are correlated into one logically contiguous file by the system without 
your needing to know the physical file location. This structure eliminates time- 
consuming disk-packing operations. 

File Structure 

A trsdos file is composed of one or more segments of storage space. Each 
segment consists of from one to 32 physically contiguous granules of storage. A 
granule is the minimum allocatable unit of storage, and consists of three sectors 

(768 bytes). 

Since a file is always lengthened by granules, a small amount of free storage is 
generally present at the end of every file. This free storage allows minor file 
additions to be made in space which is physically contiguous to the file. 

Every time a disk file is extended (either initialized or lengthened), extra 
granules may be allocated to that file, depending on the file's accumulated 

length, diskette space, saturation, etc. These extra granules, along with all 
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granules after the one containing the file's eof mark, are recovered and returned 
to the system when the file is closed. 



A TRSDOS file 

FILE; 



LRN1 



LRN2 



LRN3 



EXTENT 1 



LRNN 



EOF 



EXTENT 2 



SEGMENT: GRANULE 1 



GRANULE 2 



GRANULE 32 



GRANULE: 



SECTOR X 



SECTOR X + 1 



SECTOR X + 2 



BYTE1 


BYTE 2 


BYTE 3 




BYTE 256 



SECTOR: 

LRN: Logical Record Number, used to specify an individual, user-defined 
logical record. Such a logical record is the smallest unit of 
information which can be addressed during disk input/output (a 
physical record is the unit which is actually read from or written to 
disk). 

File: A group of logical records; the largest unit of information which can 

be addressed by a trsdos command. 

Sector: A physical record, composed of 256 contiguous bytes. 

Granule: The minimum allocatable unit of storage for any file. 

Extent: One contiguous allocation of granules. 

System Routines for Assembly-Language I/O 

This information is provided for customers who wish to write their own 
assembly level i/o routines. An explanation of the calling sequence and 
parameters for each necessary i/o routine is given. A knowledge of z~80 machine 
code is assumed. 

The following notations are standard in this section: 



(HL) = 



xxxx 



-XX 



Registers hl contain the address of (point to) xxxx in machine 
format. (If address of xxxx = 34B2H then the values in the 
registers are: h = 34; l = B2). Other register pairs will also be 
indicated this way. 

Register a contains the numeric value of xx in binary form. 
Register a is used to return the trsdos error code for i/o calls. 
A complete list of error codes and their meanings appears at 
the end of this chapter. Other registers will also be indicated 
this way. 
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Z = OK 



Zero flag is set (OK) if successful return from the system 
routines. 



x nnnn 
or nnnnn 



Hard ram address in hex notation (e.g., 402D is X'402D'). 



lrl 



Logical Record Length, 1-255 bytes only. You can define 
records any length you wish up to 255 bytes maximum. A 
length of zero is a special case for physical records only, and 
indicates the lrl = 256 bytes. 



buffer 256 user-designated bytes in ram for trsdos to read sectors 

from or write sectors into. If lrl = o, this area is the 
responsibility of the user to manage before and after i/o. trsdos 
manages this area if lrl is between 1 and 255 bytes. Do not 
alter this area when using logical record processing. 



UREC 



(User Record) The address of the contiguous ram byte-string 
assigned by the user as his logical record area. Its length must 
be equal to lrl. It is a different area from buffer. 



lsb/msb Least-significant byte followed by most significant byte. This is 

the standard z-80 format for addresses. 

%name The "$" is prefixed to all system locations and call routines, so 

they will not be confused with trsdos commands or utilities. 
For example, $open. 



DCB before $OPEN and after $CLOSE 

The dcb (device control block) is defined as 50 contiguous bytes of ram 
designated by the user. Before $open and after $close, it is a left-justified, 
compressed (no spaces) ascii string, as in a standard trsdos filespec. The string 
is terminated with a carriage return. 
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Notes: /ext, .password, and :d are optional. 
$ stands for a carriage return (X'OD') 
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DCB while $OPEN 



Address 


Length 


Explanation 


DCB + 


3 


Reserved 


+ 3 


2 


Physical Buffer address (lsb/msb) 


+ 5 




Offset to delimiter at end of current record 


+ 6 




File drive number residence 


+ 7 




Reserved 


+ 8 




eof offset of last delimiter in last physical record 


+ 9 




lrl (logical record length) 


+ 10 


2 


nrn (next record # — $open sets = x'oooo' — lsb/msb) 


+ 12 


2 


ern (ending record # — (last in file) lsb/msb) 


+ 14 


50 


Reserved 



NRN Next Record Number defines which record is to be read or written by the 
next system call for sread or swrite. It is automatically incremented by one 
after each system call. In order to process random files, use the sposn call to 
direct trsdos to the record you wish to transfer next. 

ERN Ending Record Number is the last record number currently in the file. It 
is put into the directory at sclose time, so if it is expected to be correct, the user 
must close his files after adding records to a file. This value may also be used to 
position to end of file so that new records may be added to the end of the file. To 
position to the end of file use a call to $posn with a record number of ern + i. 
$posn is described later. 

Physical and Logical Records in TRSDOS 

A physical record is defined as one sector of disk. One sector of disk contains 
256 user data bytes. The artificial term "granule" is defined to be 3 sectors of 
disk space. There are 6 granules on each of the 40 tracks on the disk. A granule 
is the least amount of space allocated by trsdos. For programming purposes, 
the physical records in a file are numbered from to N. The largest record 
number (N) in a file will then be 3 times the number of granules allocated minus 
one ((3*G) - 1). All trsdos granule allocations are made as needed at the time 
of write, not when the file is created. 



Bytes 


Sectors 


Granules 


Iracks 


Disk 


256 


1 


— 


— 


— 


768 


3 


1 


— 


— 


4608 


18 


6 


1 


— 


184320 


720 


240 


40 


1 



Disk Space Table: For each 5 l A" Disk Drive 

A logical record is defined by the user of trsdos. It may be anywhere from 1 to 
255 bytes in length. Once a file is opened with a specific lrl (Logical Record 
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Length), the length Is fixed until the file is closed. To change a file's lrl, you 
must close it and re-OPEN it with the new lrl. 

Each opening of the file sets a single, fixed record-length, trsdos will "block" 
logical records into (or from) one physical record for maximum space utilization 
on the disk. 

Blocking is putting more than one logical record into one physical record. For 
instance, four 64-byte logical records will fit into one 256-byte physical record. 
A logical record may be broken into two parts by trsdos in order to fill the last 
portion of one physical record entirely before beginning to use the next physical 
record (i.e. records are spanned). This occurs when the physical record length is 
not an even multiple of the logical record length. 

If the user wishes to do his own blocking, he may specify a logical record length 
of bytes at the time of init/open and must himself manage the contents of the 
physical record buffer area of 256 bytes, trsdos will not move a logical record 
for the user if lrl = 0; in this particular case it will only read/write the physical 
record to/from the buffer. Once control is shifted to your program, you will have 
about 20 bytes of stack size left. 

Fundamental TRSDOS I/O Calls 

There are 17 fundamental trsdos routines involved in handling file i/o. These 
are: 



$BACKSPACE 


$POSN 


$CLOSE 


$PUTEXT 


$DIVIDE 


$RAMDIR 


$DMULT 


$READ 


$FILPTR 


SREWIND 


$INIT 


$SYNTAX 


SKILL 


$VERF 


$OPEN 


$WRITE 


$POSEOF 





The detailed calling sequences and discussions for each of these routines follow. 
Note that all of these system calls use register f and do not restore its value 
before return. In order to apply this data properly, you should read through ail of 
these descriptions and clear up all of the points that are not obvious to you by 

using other reference materials. If you are successful in doing this you will find 
that trsdos is a workable tool for your programming ideas. 

$INIT— H^/X^M^' 

$init is provided as an entry point to trsdos which will create a new file entry 
in the directory and open the dcb for this file. $init scans the directory for the 
filespec name given in the dcb. If the filespec name is found, $init simply opens 
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the file for use. If the name is not found, a new file is created with the filespec 
name. 



Entry Conditions 

(HL) = buffer (see beginning of this section for notation) 

(DE) = DCB 
B = LRL 

CALL $INIT 

Exit Conditions 

iy = changed 

z = OK 

c carry flag is on if a new file was created 

a = trsdos error code. (Error codes listed at end of this chapter) 

$OPEN— 17444/X 9 4424' 

$open provides a way to open the dcb of a file which already exists in the 
directory. The dcb must contain the filespec of the file to be opened before entry 

to $OPEN. 

Entry Conditions 

(HL) = BUFFER 
(DE) = DCB 
B = LRL 
CALL $OPEN 

Exit Conditions 

Z = OK 

z = if file does not exist. 
a = trsdos error code. 
iy = changed 



$POSN — 17474/X'4442' 

$posn positions a file to read or write a randomly selected logical record. Since 
it deals with logical records, the proper computation is done to locate which 
physical record(s) contain the data. Following a sposn with a sread or swrite 
will transfer the record to/from ram. 
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Note that positioning to logical record zero sets the file to read the first logical 
record in the file. To position to end of file in order to add new records onto the 
end, use the record number ern + 1 . 

Entry Conditions 

(DE) = dcb (must have been opened previously) 
bc = Logical record number to position for. 

CALL SPOSN 

Exit Conditions 

Z = OK 

a = trsdos error code. 

$READ^ 17462/X'4436' 

If lrlo, sread transfers the logical record whose number is in the dcb as nrn 
into the ram area addressed as urec for the length lrl as defined at open time. 
The record comes from "buffer" defined at open time. If trsdos must read a 
new physical record to satisfy the request, it will do so. "Spanned" logical 
records will be re-assembled as necessary. $read automatically Increments nrn 
by 1 in the dcb after the transfer is completed. $init/open set nrn = x'oooo' in 
order to read the first record with the first read. 

If lrl = o, sread transfers one physical record into buffer, defined at open 
time, from the disk file. Registers hl are ignored. $read increments nrn as 
above. 

Entry Conditions 

(HL) = urec if lrl is not zero. Unused if lrl = o. 

(DE) = DCB 
CALL SREAD 

Exit Conditions 

Z = OK 

a = trsdos error code. (eof = x*ic or X'lD') 
(see errors 28,29 for eof or nrf) 

$WRTTE— 17465/X'4439' 

If lrlo, swrite transfers the one logical record from the ram area addressed 
as urec for the length lrl as defined at open time. The record goes into the 
buffer which was defined at open time. If trsdos must write a physical record 
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in order to satisfy the request, it will do so. "Spanning" will be handled by 
trsdos as necessary. At sinit sopen time the dcb value of nrn is set to x'oooo' 
so that the first record will be written. After each logical record is transferred, 
the nrn value in the dcb will be incremented by 1 . 

If lrl = o, swrite transfers one physical record from buffer into the disk file 
using the nrn in the dcb. buffer is defined at sinit/open time only. The dcb 
value nrn is updated as above, after the write. 



C 1 



Entry Conditions 



(HL) = urec if lrl is not zero. Unused if lrl = o 
DE = dcb 

CALL SWRITE 

Exit Conditions 

z = OK 

A = trsdos error code. 



$VERF— 17468/X'443C' 

The only difference between sverf and swrite is that sverf writes one physical 
record to disk and then reads it back into a special trsdos ram area not defined 
by the user. This special area and the original write buffer are then compared 
byte by byte to assure that the record was successfully written. 

Entry Conditions 

(HL) = Same as swrite above. 
(DE) = DCB 
CALL SVERF 

Exit Conditions 

Z = OK 

a = trsdos error code. 



$PUTEXT— 17483/X»444B' 



This routine will add an extension to a filename if an extension does not already 
exist. An extension to a filename may be useful for identifying the type of data 
in the file. 
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Entry Conditions 

(DE) = DCB 

(HL) = The extension to be added to the file 

CALL SPUTEXT 

Exit Conditions 

None 

$BKSPC — 17477/X'4445' 

This routine positions the file record pointer to the previous record. 

Entry Conditions 

(DE) = DCB 
CALL $BKSPC 

Exit Conditions 

z = Valid position 

nz = Invalid position in file 

$REWIND™- 17471/X'443F' 

Point to the beginning of the file. This routine positions the file pointer to the 
first record in the file. This is useful when the same file must be processed more 
than once. 

Entry Conditions 

(DE) = DCB 

Exit Conditions 

z = Good file specification 
nz = Bad file specification 

CALL SREWIND 



$POSEOF^ 17480/X'4448» 

Point to the end of file. This routine positions the file pointer to the last record in 
the file. This may be used to extend a sequential access file. 
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Entry Conditions 

(DE) = DCB 
CALL SPOSEOF 



Exit Conditions 

z = Good file specification 
nz = Bad file specification 



$SYNTAX— 17436/X 9 441C 9 

Move a file specification to dcb. This routine takes a file specification and 
checks it for validity and moves it to a dcb so that the file may be opened. 

Entry Conditions 

(HL) = Filename 

(DE) = DCB 
CALL SSYNTAX 



Exit Conditions 

z = Good file specification 
nz = Bad file specification 



$DIVIDE™~ 17489/X ? 4451 9 

The divide routine takes a 16-bit dividend and an eight-bit divisor. After 
division, the quotient replaces the 16-bit dividend and the remainder replaces the 
eight-bit divisor. 

Entry Conditions 

hl = Dividend 
a = Divisor 
call sdivide 



Exit Conditions 

hl = Quotient 

a = Remainder (0 indicates no remainder). 
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$DMULT — 17486/X»444E' 

The multiply routine uses a 16-bit multiplicand and an eight-bit multiplier. After 
multiplication takes place, the product replaces the 16-bit multiplicand. 

Entry Conditions 

hl = Multiplicand 
a = Multiplier 

CALL SDMULT 

Exit Conditions 

H = High order byte 

L = Middle order byte 
a = Low order byte 

H L A 



High Middle Low 



$RAMDIM^ 17040/X'4290' 

This routine allows you to examine a diskette directory (one entry or the entire 
directory) or the diskette's free space. The information is written into a user 
specified ram buffer. 

Only non-system files will be included in the ram directory. 

Entry Conditions 

hl = ram Buffer. If c = 0, size = 1761 [max #*22+ 1]. If c = i to 96, 

size = 22. If c = 255, size = 64. 
b = Specified drive number 
c = Function switch: 



Contents of C 



1-96 

255 

CALL SRAMDIR 



Results 

Gets entire directory into ram. (See ram Directory Format). 

Gets one specified directory record into ram, if it exists. (See 
ram Directory Format). 

Gets free-space information (See ram Directory Format). 



Exit Conditions 



nz = Error occurred. 

z = No error. (HL) = directory or free-space information. 
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RAM Directory Format 

The directory is made up of records, one per file. All values are hexadecimal. 
Each record placed in user ram is in the following format: 

Byte Number Contents 

0-14 file name lextid (left-justified followed by spaces) 

15 Protection Level, binary 0-6 

16 Byte eof, binary 0-255 

17 Logical record length, binary 0-255 
18-19 Last sector number in file, binary lsb, msb 
20-21 Number of Granules allocated (LSB.msb) binary 

22 " + " (marks the end of directory list after entire directory.) 

Free Space Message Format 

***nnnnn Free Granules*** 

Where nnnnn is a decimal number. The entire message is ASCII-coded. 




$FILPTR— 17037/X'428D' 

This routine provides information on any user file that is currently open. It 
enables you to obtain the drive number and the logical file number for any file 
and should be used in conjunction with sramdir. 

Entry Condition 

(DE) = Data Control Block (dcb) defined when file was opened. 

CALL SFILPTR 

Exit Conditions 

nz = Error occurred. 

z = No error. The following registers are set up: 
b = Which drive contains the file (0,1,2, or 3). 
c = Logical file number (1-96) 

Note: This operates with user files only. 

$CLOSE^ 17448/X'4428 ? 

$close closes a file from the last processing done. It is very important to do 
a Sclose on every file opened before the program ends. If you do not close 
a file, the directory entry for this file is incorrect if any new records have been 
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written into the file. Other cases are not given here, but it is very important to 
trsdos that all of the "housekeeping" be complete for file management. 

Entry Conditions 

(DE) = DCB 
CALL SCLOSE 

Exit Conditions 

Z = OK 

a = trsdos error code. 



SKILL™ 17452/X ? 442C' 

Skill deletes the directory entry for a file and releases the disk storage. The file 
may be open or closed; skill will operate in either case. 

Entry Conditions 

(DE) = DCB 
CALL SKILL 

Exit Conditions 

Z = OK 

a = trsdos error code. 



Additional Routines and Storage Addresses 
$JP2DOS — 16429/X'402D 9 

This routine transfers control to trsdos ready. 

Entry Conditions 

JP SJP2DOS 

Exit Conditions 

None 
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$DATE— 12339/X'3033' 
$TIME-™ 12342/X'3036' 

These routines return the date and time in ascii format: 

Date: mm/dd/yy 
Time: hh/mm/ss 

Entry Conditions 

(HL) = Eight-byte buffer to receive the date/time text 

CALL $DATE 
CALL STIME 

Exit Conditions 

(HL) = Date or time text 

$DATLOC — 16922/X 9 421A ? 
$TIMLOC — 16919/X'4217' 

These locations store the date and time in binary format: 

$datloc (Three bytes): yy dd yy 
STIMLOC (Three bytes): ss mm hh 

$ERRDSP— 17417/X'4409' 

This routine displays a trsdos error message determined by the contents of the 
accumulator (A). This register contains an error code (0 = no error) after 
completion of any system routine. 

Entry Conditions 

a = trsdos error code (see Table at the end of this section). In a trsdos error 
code, bits 6 and 7 are normally reset (off). So serrdsp interprets them as 
controls. 

Not Set (Normal 
Bit # Set Condition) 

7 Return to caller upon Return to trsdos upon 

completion completion 



Give detailed error message Give error number only 



call serrdsp 
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Exit Conditions 

None 

Sample Use 

CALL 4SYSRTN 5 ANY SYSTEM ROUTINE 

JR Z.OKGO 5 CHECK FOR ERROR 
5 THE FOLLOWING INSTRUCTION SETS BIT G (DETAILED 
! ERROR MESSAGE) AND BIT 7 (RETURN TO CALLER AFTER 
! DISPLAYING MESSAGE 

OR C0H 5 BINARY 11000000 

CALL $ERRDSP ! NOW CALL ERROR DISPLAY 
5 CONTINUE HERE UPON RETURN FROM ERROR DISPLAY 
i YOUR ERROR HANDLER MAY GO HERE 
5 : 

5 : 

j ; 

OKGO ICONTINUATION AFTER $SYSRTN WITH NO ERROR 

$DSPDIR^ 17433/X'4419' 

This command displays the directory listing of all non-protected user files in a 
specified drive. 

Entry Conditions 

(X'427i') = ASCII-coded drive number "0," "1," "2," or "3" 

CALL SDSPDIR 

Exit Conditions 

All registers are changed. 

$COMDOS — 17049/X'4299' 

This routine executes a trsdos command and returns to trsdos ready. 



Entry Conditions 



(HL) = Text of trsdos command, terminated by x'od: 

JP SCOMDOS 

Exit Conditions 

None 



88 



— ^ ^ ^:%a-:^-w 



a 



$CMDDOS — 17052/X»429C ' 

This routine executes a trsdos command and returns to the caller. 

Entry Conditions 

(HL) = Text of trsdos command, terminated by X'OD.' 

Exit Conditions 

All registers are changed. 

Caution: trsdos commands will overlay ram up to x'6fff.' 

$CMDTXT — 16933/X'4225' 

This is the start address of a buffer containing the last command line entered 
under trsdos ready. Using this buffer, your program may recover parameters 
that were included in the last command line. 

For example, given a program named editor/cmd, we want the operator to 
select an input file name when the program is loaded and executed from trsdos 
ready: 

trsdos ready 
editor myfile 

The program, editor, can recover the name of the file in the scmdtxt buffer. 

Note: On entry to a program, (HL) = First non-blank character following the 
program name. 

$MEMEND— 17425/X'4411' 

This storage location contains the highest address available. It is normally the 
same as the physical end of ram, but you may change it for special purposes. 

The address is in lsb, msb sequence. 
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TRSDOS Error Codes/Messages 

No Error Found 

1 CRC Error During Disk I/O 

2 Disk Drive Not in System 

3 Lost Data During Disk I/O 

4 CRC Error During Disk I/O 

5 Disk Sector Not Found 

6 Disk Drive Hardware Fault 

7 "Undefined Error Code** 

8 Disk Drive Not Ready 

9 Illegal I/O Attempt 

10 Required Command Parameter Not Found 

1 1 Illegal Command Parameter 

12 Time Out On Disk Drive 

1 3 I/O Attempt To Non-System Disk 

14 Write Fault On Disk I/O 

15 Write Protected Disk 

16 Illegal Logical File Number 

17 Directory Read Error 

18 Directory Write Error 

19 Invalid File Name 

20 GAT Read Error 

21 GAT Write Error 

22 HIT Read Error 

23 HIT Write Error 

24 File Not Found 

25 File Access Denied Due to Password Protection 

26 Directory Space Full 

27 Disk Space Full 

28 Attempt to Read Past EOF 

29 Attempt to Read Outside of File Limits 

30 No More Extents Available 

31 Program Not Found 

32 Invalid Drive Number 

33 "Undefined Error Code** 

34 Attempt to Use Non-program File as a Program 

35 Memory Fault During Program Load 

36 "Undefined Error Code** 

37 File Access Denied Due to Password Protection 

38 I/O Attempt to Unopen File 

39 Invalid Command Parameter 

40 File Already In Directory 

41 Attempt to Open File Already Open 
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Introduction 



Start-Up 



Under trsdos ready, type: 

BASIC flNTEffi 

trsdos will load basic and begin the "initialization dialog." 

If you want to recover a Disk basic program after returning to trsdos for a dir 
or other trsdos command, use this command under trsdos ready: 

BASIC * CENTO 

You will go directly to Basic's ready mode without any initialization dialog. If 
you had a program in memory, it should still be there. You may not be able to 
run the program. To be safe, you should immediately save the program, go to 
trsdos, then start basic again (no asterisk). 

Note: If you have overlaid user memory while in trsdos, your program will be 
erased. In such a case, you should not restart basic, but should use the normal 
basic start-up procedure. 



Initialization 

When you start Disk basic, you are first asked, HON MANY FILES?. This lets 
you specify the maximum number of files that will be "open " or in use at once. 
(See open.) Type in an appropriate number and press (ENTER), or simply press 
(ENTER) and basic will provide for three files. 

For example, if your program requires one input file and one output file, you 
should ask for two files. 

Note: Normally, basic will give all your data files a record length of 256. 
(See File Access Techniques.) If you wish to set the record length of each file 
individually, use the suffix v for "Variable" after the number of files. 
For example, 

HOW MANY FILES? 3M (ENTER) 

tells basic to give you three ile-buffers, and to let you set the record length of 
each file when that file is first opened. 

Note: Disk basic automatically creates a buffer for loading, saving, and 
merging basic programs. This buffer exists in ram below any data file buffers 
you may request. It is always available for program i/o, regardless of how you 
answer the files? question. 
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After you an swer the files question, basic will ask: MEMORY SIZE? Simply 
press ( ENTER ) without typing a number. You will then have the maximum amount 
of ram available for use by basic. 

If you will want to load and use machine-language programs or routines, you 
will have to protect your basic memory from these machine-language programs. 

In such a case, respond with the highest memory address (in decimal form) you 
want basic to use for storing and executing your basic programs. Addresses 
above the number you specify will then be protected from use by basic. 

Example: 

MEMORY SIZE? 32000 (tWTlf) 

causes basic to protect addresses above 32000. If you have 16K of ram, this 
means that you'll have 32767-32000 = 767 bytes protected for storing your 

machine-language routines. 

After you answer the MEMORY SIZE? question, Disk basic will display the 
following information: 

1 . Which version of Disk basic you are using 

2. Copyright information 

3. The number of free bytes available 

4. The number of concurrent files you have requested. 

To exit from Disk basic and return to the trsdos ready mode, type: 
CMD"S" (ENTER) 

This results in a normal return to trsdos, without re-initialization of the system. 
You may recover your program if you haven't changed user memory while in 
trsdos. Use BASIC *. 
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Enhancements to Model HI BASIC 



Disk basic adds many features which are not disk-related. They are listed below 
along with abbreviated descriptions. Detailed descriptions follow in alphabetical 
order. 



&H 

&o 
Abbreviations 

CMD"A" 

CMD"B" 

CMD"C" 

CMD"D" 

CMD"E" 

CMD'T' 

CMD'T ' 

CMD"L" 

CMD"0" 

CMD'T" 

CMD"R" 

CMD"S" 

CMD'T" 

CMD"X" 

CMD"Z" 
DEFFN 
DEF USR 

INSTR 
LINE INPUT 

MID$ = 

NAME 

usRn 



Hexadecimal-constant prefix 

Octal-constant prefix 

Many commands have abbreviations 

Return to trsdos with error message 

Enable/Disable (BREAK) 

Delete spaces and remarks from a program (compression) 

Display directory for specified drive 

Display previous trsdos error 

Return a command to trsdos 

Convert calendar date 

Load z-80 subroutine or program file into ram 

Alphabetizes (sorts) a string array only 

Check printer status 

Start real-time clock display 

Normal return to trsdos (jump to exit routine) 

Turn off real-time clock display 

Cross-reference of reserved words, string variables, or 

strings in a program 

Duplicate output to Display and Printer 

Define BASic-statement function 

Define the entry point for an external machine-language 

routine 

Instring function; find the substring in the target string 

Input a line from keyboard 

Replace portion of the target string (used on left of equals 

sign) 

Renumber a program in ram 

Call external routine (n = 0,l,2, . . . ,9) 



&H and &O (hex and octal constants) 

Often it is convenient to use hexadecimal (base 16) or octal (base 8) constants 
rather than their decimal counterparts. For example, memory addresses and byte 
values are easier to manipulate in hex form. &H and &o let you introduce such 
constants into your program. 

&H and &o are used as prefixes for the numerals that immediately follow them: 
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&»dddd 



dddd is a 1 to 4 digit sequence composed of hexadecimal numerals 
0.1....9.A.B F. 

zaddddd 

ddddd is a sequence of octal numerals 0,1... 7 and &oddddd =177777 
decimal. 

Note: The o can be omitted from the prefix &o. Therefore &oddddd= &ddddd. 



The constants always represent signed integers. Therefore any hex number 
greater than &H7FFF, or any octal number greater than &077777, will be 
interpreted as a negative quantity. The following table illustrates this: 

Octal Hex Decimal 



&1 


&H1 


1 


&2 


&H2 


2 


&77777 


&H7FFF 


32767 


& 100000 


&H8000 


-32768 


&1 00001 


&H8001 


-32767 


& 100002 


&H8002 


-32766 


& 177776 


&HFFFE 


-2 


& 177777 


&HFFFF 


-1 



Hex and octal constants cannot be typed in as responses to an input prompt 
or be contained in a data statement. Often the hex or octal constant must be 
enclosed in parentheses to prevent a syntax error from occurring. 

Examples 

PRINT &H5200, &O51000 

prints the decimal equivalent of the two constants (both equal 20992). 

POKE &H3C00* 42 

puts decimal 42 (ascii code for an asterisk) into video memory address hex 

3C00. 
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Model III Disk BASIC Abbreviations 



Abbreviation 


Meaning 


® 


List Previous Program Line 


® 


List Next Program Line 


CD 


List Current Program Line 


CD 


Edit Current Program Line 


(SHIFT) (*-J 


List First Program Line 


(SHIFT) (♦) CZJ 


List Last Program Line 


LXX 


List Program Line xx 


EXX 


Edit Program Line xx 


DXX 


Delete Program Line xx 


AXXX,XXXX 


Automatic Line Numbering Beginning at Line xxx, 




Incrementing byxxxx. 



CMD "A ?? 
Return to TRSDOS 



CMD'A' 



This command allows you to return to trsdos with an error message: 
OPERATION ABORTED 

Sample Use 

After an input/output error occurs in a basic program, you might want to exit to 
trsdos and print a message. 

CMD" A" 

the following will be displayed: 

OPERATION ABORTED 
TRSDOS READY 
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CMD "B" 

Enable/Disable BREAK Key 



cmd'B", "switch" 

switch is either on or off. switch must be enclosed in quotation marks. 



Thi s comm and enables or disables the (BREAK) key. While the function is "off," 
the ( BREAK ) key will be ignored except during cassette or printer output or during 
serial input/output. 



The (BREAK) key w ill remain disabled even after the program has ended. To 
enable the ( BREAK ) key, use the cmd"B","ON" command. Returning to trsdos 

via the cmd"S" or cmd'T' commands will also enable the (BREAK) key. 

Examples 

CMD"B" ,"0FF" 

Disables the (BREAK) key. 

CMD"B" » "ON" 

Returns the (BREAK) key to its norma! function. 



CMD "C" 

Compress Program 



cmd c , options 



options may be either r (delete remarks) or s (delete spaces). If both 
options are omitted, remarks arid spaces are deleted. If only one is 
omitted, only the specified action is taken. 



This command allows you to compress a program so that it requires less 
ram and less storage space on diskette. You can elect to remove all remark 
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statements (beginning with rem or ') or to delete all spaces between basic 
keywords. Spaces inside quotes will not be deleted. 

Example 

Your program reads as follows: 

850 RESTORE: ON ERROR GOTO 800 'DOG PROGRAM 

860 READ COMPANY* 'PET STORE 

870 PRINT RIGHT$(C0MPANY*»2)»: GOTO 8G0 
880 END 

If you want to delete the Remarks (lines 850 and 860), type in the command: 

CMD"C" »R 

and the program will now read: 

850 RESTORE: ON ERROR GOTO 800 

8G0 READ COMPANY* 

870 PRINT RIGHT*(C0MPANY*»2> t:G0T0 8G0 

880 END 

If you then wanted to delete the spaces, type in: 

CMD"C" »S 

and the program would read: 

850 RESTORE : ONERRORGOTO800 

860 READCOMPANY* 

870 PRINTRIGHT*(C0MPANY*»2) ,:GOTO8G0 

880 END 

You could obtain the same results by typing: 
CMD"C" 

Note: Always provide the closing quotes on string literals in your basic 
program. Otherwise cmd"C" may not function properly. For example, in 

10 PRINT "THIS IS A TEST" 

the second quote should be used even though omitting it will not cause an error. 

CMD"D' 9 

Display the Directory of a Specified Drive 



cmd"d:«F' 

dis the drive specification 
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By entering the command cmd"d:<P, you can obtain a specified diskette's 
directory from basic without returning to trsdos. Only unprotected, visible 
files will be displayed. The drive specification is not optional and must be 
specified for all drives, including Drive 0. 

Example 

If you type in the command: 

CMD"D:i" 

the directory for Drive 1 will be displayed. 

CMD"E" 

Display Previous TRSDOS error 



CMD'E" 



This command displays the last trsdos error message. If no errors have 
occurred prior to the command, the message NO ERROR FOUND will be 
displayed. 

Example 

If you have a two-drive system (0 and 1) and you type: 

SAME "PROGRAM: 3" 

Disk basic will return a DISK I/O ERROR. To find out what kind of i/o error 
occurred, type: CMD " E " (ENTER) and Disk basic will return with DISK DR I ME 
NOT IN SYSTEM. 

CMD"I" 

Execute TRSDOS Commands from Disk BASIC 



i . command 

command is 3 string expression containing a thsdos command or a z-eo 
program file siame. H it is a string constant it must be enclosed in 
Quotes. 
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You may execute trsdos commands directly from basic by using cmd"I". 

This is similar to cmd"S", except that it lets you include a command or z-80 
program for trsdos to execute. 

As long as basic is not overwritten by the execution of the program or 
command, control will return to basic; otherwise, control will return to trsdos. 
(trsdos commands all overlay basic; your z-80 program may not if it loads 
above basic.) 

Example 

CMD"I" ."PROGRAM" 

returns you to trsdos and executes the program file program. 
CMD"I" »A* 

returns you to trsdos and executes the command contained in a$. 

CMD"J" 

Calendar Date Conversion 



cmd : 'J", source, desilmim 

contents may fie in eiihsr m two formats: 
A) mnt/ad/yy 

format a gives ths fiats in month-flay- par sequence. Format b giwes 
the day of Ins m$> (from f to 365 m 386 to leap pars), in format b, 
the hyphen is required. 

format a : mslmzilm w\\ contain tee day oi year. !f soiree is in 
format s, assiifimnn will contain ths dale m format a. 



This command converts dates back and forth between two formats: the standard 
month, day, year, sequence; and a year, day of year, sequence. The content of 
the source string determines which way the conversion goes. 
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Example 

CMD"J" , "11/30/80" , D$ 

Returns the day of the year in d$. 

CMD"J" , "-79/300" t D$ 

Returns the month, day, year, equivalent in d$ (the date for the 300th day 
of 1979). 

Sample Program 

10 CLEAR 50 

20 LINE INPUT"ENTER FIRST DATE (MM/DD/YY) "5 FD$ 

30 LINE INPUT"ENTER SECOND DATE (MM/DD/YY) "5SD$ 

40 CMD"J" t FD$> Dl* 

50 CMD"J" , SD$» D2$ 

G0 Yl = VAL(RIGHT*(FD*»2> ) 

70 Y2 = UAL ( RIGHT* (SD$>2) ) 

80 Jl = VAL(RIGHT$(D1$*3) ) 

90 J2 = MAL(RIGHT$(D2*»3) ) 

100 SI = Y1*3G5 + Jl 

110 S2 = Y2*3G5 + J2 

120 PRINT "THE INTERVAL BETWEEN DATES IS" 5 

130 PRINT ABS(S1-S2H "DAYS "5 

140 PRINT "(IGNORING LEAP-YEARS)," 

150 INPUT "<ENTER> TO CONTINUE" I A$ 

160 GOTO 20 

CMD"L" 

Load Z-8© Routine Into MAM 



cmd l ;rov(ine 



routine is a spring ajqir^ssior; eomsmlRe a ^iie specification for a i aa 
routine or p?o^s<r: c-aEfeo by 'M t^haf •czxrmmii. !r routine h a 
sSr!ng corssra*:!.. ! A mm' be wmhsi in quotes 



cmd"L" loads a z-80 (machine- language) routine into ram. It would normally 
be used to load a z-80 subroutine which is to be accessed directly from basic. 



100 



DISK BASIC I 



The z-80 routine should load Into high-RAM and must not overlay the memory 
protect area reserved when you first entered basic (i.e. , the MEMORY SIZE? 
prompt). If you do not overlay basic or trsdos, control will return to basic 
after the program is loaded. 

Example 

The command: 

CMD"L" ."PROG" 

will load a program file named prog into ram. 

CMD"L" *P$ 

will load a program which has been specified as p$. 



CMD"0" 

Sort ("Order") an Array 



mD"Q'\x, array (start) 

array may be of any length. 



This command sorts (orders) a one-dimensional string array, I.e., a list. You 
may sort all or part of the array, depending on the values you give to x and start. 

Sample Program 

10 CLEAR 10 * 25 + 50 'ROOM FOR 10 WORDS + EXTRA 

20 DIM A$C95 'LIST OF TEN (0-9) 

30 FOR WD = TO 9 

m PRINT "ENTER WORD *"! WD+1 

50 INPUT A$(WD) 

60 NEXT WD 

70 NI=10: CMD"0" > Hit A$(0) 

80 PRINT "HERE IS THE SORTED LIST" 

90 FOR WD=0 TO 9 
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100 PRINT A*(WD) 
110 NEXT WD 



CMD"P" 

Check Printer Status 



cmd' p: status 

status is a siring variable 



cmd"P" makes it possible for Disk basic to check the status of the printer. 

Unlike the video display, the printer is not always available. It may be 
disconnected, offline, out of paper, etc. In such cases, when you try to output 
information to the printer, the Computer will wait until the printer becomes 
available. It will appear to "hang up." To regain keyboard control (and cancel 
the printer operation), press (BREAK) . 

Suppose you have a program which uses printer output. If a printer is not 
available, you don't want the Computer to stop and wait for it to become 
available. Instead, you may want to print a message such as PRINTER 
UNAVAILABLE and go on to some other operation. 

To accomplish this, you need to check the printer status. cmd"P" can be used to 
check the printer's status at any time. It returns the contents as an Ascii-coded 
decimal number. The specific value of this number depends upon the type of 
printer you are using as well as its status at any particular time. The value may 
then be printed or examined by the program. 

Only the four most significant bits are used in this "status byte." In binary, 
these must be: "0011" or else the print operation will not be attempted. To 
check for this "go" condition, and the status byte with 240 and compare the 
result with 48. The meaning of each status bit depends on which printer you 
use. See the printer owner's manual for bit designations. 



Sample Program 



10 CMD"P" ,){% 

20 ST% = VAL <>($} AND 250 

30 IF SU <> 38 THEN PRINT "PRINTER UNAVAILABLE": STOP 

40 PRINT "PRINTER AVAILABLE" 

50 REM PROGRAM MAY NOW CONTINUE 
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CMD"R ?9 

T\irn On Clock-Display 



CMD "R 



This command controls the real-time clock display in the upper-right corner of 
the Video Display. When it is on, the 24-hour time will be displayed and 
updated once each second, regardless of what program is executing. 

Note: The real-time clock is always running (except during cassette or disk i/o), 
regardless of whether the display is on or off. 

Example 

To turn on the clock display type: CMD " R " To turn the display off, type: CMD " T " 

CMD"S" 

Return to TRSDOS 



CMOS' 



To exit from Disk basic, returning control to trsdos, simply type in the 
command: 

CMD"S" 

To return to basic and recover your program, use B AS I C *. However, recovery 
will not always be possible. See basic *. 

Example 

The basic prompt lets you know you are in Disk basic. 

READY 
> 
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To exit, type In: 

CMD"S" 

and the trsdos prompt will appear. 

TRSDOS READY 



*S4$$*5**S***$$4$ 



CMD"T" 

Ikrn Off Clock-Display 



i,hfSIVV 



This command turns off the real-time clock display function. 
However, the clock continues to run. 

Example 

To stop the clock display update type: CHD"T" 
To start the display, type: CMD"R" 

CMD "X" 

Cross-reference of Program Lines 



or'iP * . irfftjs.- 
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This command finds all occurrences of a reserved word or other string literal in 
the resident program. The "finds" are listed on the display as five-digit line 
numbers. 

To search for any basic reserved word (including reserved arithmetic operators), 
use the keyword as-is. To search for anything else (including variable-names and 
text), enclose the text inside quotes. 

For example, suppose you have the following program in memory: 

10 PRINT "THIS IS A TEST" 

20 INPUT "PRESS <ENTER> FOR THE NEXT PRINT MESSAGE"! Z$ 

30 A = A + 1 

40 PRINT "+++++++" 

CMD " X " > PRINT will find all occurrences of print, except for cases where 
print was part of a quoted string: lines 10 and 40. 

CMD "X" i "PRINT" will find all occurrences of "print" as a string literal: line 
20. 

CMD "K" , + will list line 30, but CMD "X" » " + " will list line 40. CMD "X" > 
"A" will list lines 10, 20, and 30. Notice that variables and text are both treated 
as string literals. 

CMD "Z" 

Duplicate Output to Video and Printer 



cmd z "switch" 

switch is either on or or switch ifius-i be snciofeea In quotation marks. 




This command enables or disables dual video/printer output. While the function 
is "on," all video output is copied to the printer, and all printer output is copied 
to the video. (The printer must be on-line when you turn dual output "on.") 

Video and printer output may differ due to intrinsic differences in the printer and 
video devices. 

Examples 

CMD "Z" » "ON" 

Turns dual video/printer output on. 
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CMD"Z" , "OFF" 

Turns dual video/printer output off. 

DEFFN 
Define Function 



owm function name {argmneri!--; ; -. ;rrr-:uis 

function na-rig s «py xdMC ism?':. -■? -•■■ 

argumeni-1 anri si&ssciie»iv s! , g!, : rr. <<.;>!?■ •?:■> ^-&r: •■" '^ : - : * v v H ^- - : ' 
fiincfiosi das?. 

formula is an sxprsssic-s f.s^s=f« ■"iv !i r*p "'* -. :^k?' v? ; ;^a^ ^r. 
the left side of the equals sign. 



The def fn statement lets you create your own function. That is, you only 
have to call the new function by name, and the associated operations will 
automatically be performed. Once a function has been defined with the deffn 
statement, you can call it simply by inserting fn in front of function name. You 
can use it exactly as you might use one of the built-in functions, like sin, abs, 
and strings. 

The type of variable used for function name determines the type of value the 
function will return. For example, if function name is single precision, then that 
function will return a single-precision value, regardless of the precision of the 
arguments. 

The particular variables you use as arguments in the def fn statement 
(argument-1, . . .) are not assigned to the function. When you call the function 
later, any variable name of the same type can be used. 

Furthermore, using a variable as an argument in a def fn statement has no effect 
on the value of that variable. So you can use that particular variable in another 
part of your program without worrying about interference from def fn. 

The function can be defined with no arguments at all, if none are required. 
For example: 

DEF FNR = RND (90) + 9 

defines a function to return a random value between 10 and 99. 
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Examples 

DEF FNR(AtB) = A + INT((B - (A - 1)) * RNDC0)) 

This statement defines function fnr which returns a random number between 
integers A and B. The values for A and B are passed when the function is 
"called," i.e., used in a statement like: 

Y = FNRtRl > R2) 

If ri and R2 have been assigned the values 2 and 8, this line would assign a 

random number between 2 and 8 to y. 

DEF FNL$<>!) = STRING* (X. "-") 

Defines function fnl$ which returns a string of hyphens, x characters long. 

The value for x is passed when the function is called: 

PRINT FNL*(3) 

This line prints a string of 30 hyphens. 

Here's an example showing deffn used for a complex computation-^ in 

double-precision. 

DEF FNX*(A#» B*> = (A# - B*) * (A* - B#> 

Defines function fnx# which returns the double-precision value of the square of 
the difference between a# and B#. The values for A# and B# are passed when 
the function is called: 

S# = FNX*(A»» B«) 

We assume that values for a# and b# were assigned elsewhere in the program. 

Sample Program 

710 DEF FNV(T) = (1087 + S0R(273 + T))/1G,52 
720 INPUT "AIR TEMPERATURE IN DEGREES CELSIUS" I T 
730 PRINT "THE SPEED OF SOUND IN AIR OF" T "DEGREES 
CELSIUS IS" FNV(T) "FEET PER SECOND," 
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DEFUSE 

Delne Point of Entry for USM Routine 



s.'; - address 

n equals osse of tne digits : 1 . . . . S: it « is an-itied. G is assumed, address 
specifies the erdry address ?c g machine-language routine. address 
must be in the .ange [ -32768,32767]. addressing be any numeric 
expression or constant from -32768 to 32767. 



defusr lets you define the entry points for up to 10 machine-language routines. 
In non-Disk basic, the addresses were POKEd into ram. This poke method 
cannot be used in Disk basic. 

Examples 

DEFUSR3 = 8.H7D00 

assigns the entry point X'7D00', 32000 decimal, to the USR3 call. When your 
program calls USR3, control will branch to your subroutine beginning at X'7D00\ 

DEFUSR = (BASE + IB) 

assigns start address (base + 16) to the usro routine. 

Note: When decimal addresses are given, they are evaluated as signed two-byte 
integers. So, for addresses above 32767, use desired decimal address -65536. 
See usrh. 

INSTR 

Search for Specified String 



position specifies the position in string 1 where the? search is to begin. 
position is optional; iJ ft ss not supplied, search automatically begins 
at the first character in string ?. {Position 1 is the first character in 
stmo 1 ' 
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This function lets you search through a string to see if it contains another string. 
If it does, instr returns the starting position of the substring in the target string; 
otherwise, zero is returned. Note that the entire substring must be contained in 
the search string, or zero is returned. Also, note that instr only finds the first 
occurrence of a substring at the position you specify. 

Examples 

In these examples, a$ = "Lincoln": 

INBTR(A$» "INC") 

returns a value of 2. 

INSTR (Mt "12") 

returns a zero. 

INSTR(A$» "LINCOLNABRAHAM") 

returns a zero. For a slightly different use of instr, look at 

INSTR (3» "1232123" , "12") 

which returns 5. 

Sample Program 

This program gets search and target text from the keyboard, then locates all 
occurrences of the target text in the search text. Line 90 is just for "show." 

10 CLEAR 1000 

20 CLS 

30 INPUT "SEARCH TEXT" 5 S$ 

40 INPUT "TARGET TEXT" I T* 

45 CLS 

50 C = : P = 1 'P = POSITION* C = COUNT 

G0 F = INSTR(P»S$»T$) 

70 IF F = THEN 120 

80 C = C + 1 

90 PRINT @B»LEFT$(S$ ! F-1) + STRING$CLEN< T*) . 191 ) + 

- RIGHT* (S*»LEN(S$)-F-LEN(T*)+1) 
100 P = F + LEN(T$) 

110 IF P <= LEN(S$) - LEN(T$) + 1 - THEN 60 
120 PRINT "FOUND "5 C! "OCCURRENCES" 
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LINE INPUT 

Input a Line from Keyboard 



line input "prompt" ;variabls 

fj'ompi is a promp*m§ messaye. 

variable is \m rmr.e thai will be assigned to the line you type in. 



line input (or lineinput — the space is optional) is similar to input, except: 

* The Computer will not display a question mark when waiting for your 
operator's input. 

• Each line input statement can assign a value to just one variable. 

8 Commas and quotes your operator can use as part of the string input. 

* Leading blanks are not ignored — they become part of variable. 

• The only way to terminate the string input is to press (ENTER) . 

line input is a convenient way to input string data without having to worry 
about accidental entry of delimiters (commas, quotation marks, colons, etc.). 
The (ENTER) key serves as the only delimiter. If you want anyone to be able to 
input information into your program without special instructions, use the line 
input statement. 

Some situations require that you input commas, quotes and leading blanks as 
part of the data, line input serves well in such cases. 

Examples 

LINE INPUT A* 

Input a$ without displaying any prompt. 

LINE INPUT "LAST NAME > FIRST NAME? " SN$ 

Displays a prompt message and inputs data. Commas will not terminate the 
input string, as they would in an input statement. 

Sample Program 

200 REM CUSTOMER SURVEY 
205 CLEAR 1000 
207 PRINT 
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210 LINE INPUT "TYPE IN YOUR NAME "5 A$ 

220 LINE INPUT "DO YOU LIKE YOUR COMPUTER? "I B* 

230 LINE INPUT "WHY? "! C* 

235 PRINT 

240 PRINT A* : PRINT 

250 IF B$ = "NO" THEN 270 

2G0 PRINT "I LIKE MY COMPUTER BECAUSE » ! C$ ;END 

270 PRINT "I DO NOT LIKE MY COMPUTER BECAUSE "! C* 

Notice that when line 210 is executed, a question mark is not displayed after the 
statement, "Type in your name." Also, notice on line 230 you can answer the 
question '''Why" with a statement full of delimiters, commas and quotes. 

MID$ = 

Replace Portion of String 



wins (oidsiring. f-osiiw-. ;sncih} - rg&acm.zr'-^ ■:<■■.. 

oidstring is the variaJste-name j' *>>? suing ycr: --wi' ■.': i-i'-sr^e 

position is the numeric expressioi? spesi'ying ihs a*ir3 : : or IH ?i ; £t 
character to be changed. 

length is a numeric expression specifying the rsiirrbsr si crtarsnm te ne 



fipri nnrh 



replacement-string Is 3 string expression to ^sacs m sfjtc^sz 
of oidstring. 

Note: If replacement-string is shorter tea*, /g^. tug;-, she entire ;'£s?8^n^ 
sfr//igwiil be used. 



This statement lets you replace any part of a string with a specified new string, 
giving you a powerful string editing capability. 

Note that the length of the resultant string is always the same as the original 
string. 

Examples 

A$ = "Lincoln" in the examples below: 
MID*(A*» 3, U) = "12345"; PRINT A$ 
which returns LH234N. 
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MID$(A$ S i , 2) = "": PRINT A$ 

which returns Lincoln. 

MID$SA$* 5) = "12345": PRINT A$ 

returns lino 23. 

MID$(A$* 5) = "01": PRINT A$ 

returns lincoin. 

MID$(A$> 1*3)= "***"; PRINT A$ 

returns ***coln. 



Sample Program 



770 CLS: PRINT: PRINT 

780 LINE INPUT "TYPE IN A MONTH AND DAY MM/DD, "i S$ 

790 P = INSTR(S$» "/") 

800 IF P = THEN 780 

810 MID*(S*» P. 1) = CHR$(45) 

820 PRINT S$ " IS EASIER TO READ* ISN'T IT?" 

This program uses instr to search for the slash ("/")• When it finds it 
(if it finds it), it uses mid$ = to substitute a " — " (chr$(45» for it. 



NAME 

Renumber the Current Program 



name newSine, startiine, increment 
If omitted, 10 is used. 

riZ : V:>:e 5pe^f-v-?- "W j?:# Vi; ~-v ; =; ':• ;K= -yen?,. -:.-vv^.>r. ^^^ 

renumbered. 

increment spes'tYm the increment to be used between each successive line 

number. If emitted, 10 !s used. 
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Examples 

NAME 

Renumbers the entire program: 10, 20, 30, . . . 

NAME 6000*50130 .100 

Renumbers all lines numbered from 5000 up; the first renumbered line will 
become 6000, and the following lines will be incremented by 100. All line 
references within your program will be renumbered also. 

USRn 

Call to User's External Subroutine 



r 



pj* 



usr.i (nmexp) 

where n specifies one of ten available \isn caiis. /? = 0.1,2. . .9. If /fls 
omitted, zero is assumed. 

nmexp is an integer from - 32788 to 32767 artri is passed 3S an iriegsr 
argument to the routine. 



These functions (usro through USR9) transfer control to machine-language 
routines previously defined with defusr« statements. 

When a urs call is encountered in a statement, control goes to the address 
specified in the defusrm statement. This address specifies the entry point to your 
machine-language routine. 

Note: If you call a usrm routine before defining the routine entry point with 
defusr/i, an illegal function call error will occur. 

You can pass one argument and retrieve one output value directly via the usr 
argument; or you can pass and retrieve arguments indirectly via poke and peek 
statements. 

Example 

1.0 DEFUSR1=&H7D00 

20 REM... MORE PROGRAM LINES HERE 

100 A=USRi(X) 

The effect of this sequence is to: 



: 3*giwygBFV~:T:*i c -■ ;!■".:- ■_;■_■_ -V - ■■.:.! ... ' : ■ '" '....■:""" .;... ■■•■.... 
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1 . Define usr as a routine with an entry point at hex 7D00 (line 10). 

2. Transfer control to the routine; the value x can be passed to the routine if the 
routine makes the call described below (line 100). 

3. When the routine returns to basic, the variable A may contain the value 
passed back from the routine (if your routine makes the jump described 
below); otherwise a will be assigned the value of x (line 100). 

Passing arguments to and from USR routines 

There are several ways to pass arguments back and forth between your basic 
main program and your usr routines: the two major ways are listed below. 

1. poke the argument(s) into fixed ram locations. The machine-language routine 
can then access these values and place results in other ram locations. When 
the routine returns control to basic, your program can peek into these 
addresses to pick up the "output" values. This is the only way to pass two 
or more arguments back and forth. 

2. Pass one argument to the routine as the argument in the usRn call, then use 
special ROM calls to access this argument and return a value to basic. This 
method is limited to sending one argument and returning one value (both 
are integers). 

rom Calls 



call 0A7FH Puts the usr argument into the hl register pair; H contains msb, l 
contains lsb. This call should be the first instruction in your usr 
routine. 

jp 0A9AH Use this jump to return to basic; the integer in hl becomes the 
output of the usr call. If you don't care about returning hl, then 
execute a simple RETurn instruction instead of this jump. 

Listed below is an assembled program to white out the display (an "inverse" 
clear key!). Don't type it in. Type in the basic program that follows it. 



7D00 



3C00 
00BF 
I3FF 



00100 


! 






00110 


; ZAP OUT 


SCREEN 


USR FUNCT 


00120 


1 






00130 




ORG 


7D00H 


00140 


I 






00150 


i EQUATES 






00160 


! 






00170 


VIDEO 


E0U 


3C00H 


00180 


WHITE 


EQU 


0BFH 


00190 


COUNT 


EQU 


3FFH 


00200 


5 






00210 


! PROGRAM 


CHAIN 


HOMES X'BF 


00220 


; 







5 START OF VIDEO RAM 
IALL WHITE GRAPHICS BYTE 
5 NUMBER OF BYTES TO MOVE 

INTO ALL OF MI DEO RAM 
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5SOURCE ADDRESS 


7D00 


21003C 


00230 ZAP 


LD 


HL .VIDEO 


7D03 


3BBF 


00240 


LD 


(HLS .WHITE 


5 PUT OUT 1ST BYTE 


7D05 


11013C 


00250 


LD 


DE.MIDEO+1 


^DESTINATION ADDRESS 


7D08 


01FFB3 


00260 


LD 


BC .COUNT 


I NUMBER OF ITERATIONS 


7D0B 


EDB0 


00270 
00280 ; 


LDIR 




iDO IT TO IT! ! ! 


7D0D 


C9 


00290 


RET 




! RETURN TO BASIC 


7D00 




00300 


END 


ZAP 





This routine can be POKEd Into ram and accessed as a usr routine. First start basic and answer the 
MEMORY SIZE question with 31999. Then ran the program. 

100 ' PROGRAM: USR1 

110 ' EXAMPLE OF A USER MACHINE LANGUAGE FUNCTION 

115 ' DEPRESS THE '@' KEY WHILE NUMBERS ARE PRINTING TO STOP 

120 ' 

130 / ♦**#*#* POKE MACHINE PROGRAM INTO MEMORY ******* 

140 ' 

150 DEFUSR1 = &H7D00 

160 FOR X = 32000 TO 32013 '7D00 HEX EQUAL 32000 DECIMAL 

170 READ A 

180 POKE X. A 

190 NEXT X 

192 ' 

194 ' ******* CLEAR SCREEN & PRINT NUMBERS 1 THRU 100 ******* 

196 ' 

200 CLS 

205 PRINT TAB(15)5 "WHITE-OUT USER ROUTINE"; PRINT 

210 FOR X = 1 TO 100 

220 PRINT X! 

225 A$ = INKEY*: IF A$ = "@" THEN END 

230 NEXT X 

240 ' 

250 ' ******* JUMP TO WHITE-OUT SUBROUTINE ******* 

2G0 ' 

270 X = USR1 (0) 

280 FOR X = 1 TO 1000: NEXT X 'DELAY LOOP 

290 GOTO 200 

300 ' 

310 / ###*#** DATA IS DECIMAL CODE FOR HEX PROGRAM ******* 

320 ' 

330 DATA 33.0.60.54.191 .17.1 .60.1 .255.3.237.176.201 

Run the program. An equivalent basic white out routine takes a long time by comparison! 



f^>~^-'7l7^Til 
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Disk-Related Features 

Disk basic provides a powerful set of commands, statements and functions 
relating to disk i/o under trsdos. These fall into two categories: 

1. File manipulation: dealing with files as units, rather than with the distinct 
records the files contain. 

2. File access: preparing data files for i/o; reading and writing to the files. 

Under the heading, Fie Manipulation, we will discuss the following 
commands. 

kill Delete a program or data file from the disk 

load Load a basic program from disk 

merge Merge an ASCII-format basic program on disk with one 

currently in ram 

run" 'program" Load and execute a basic program stored on disk 

save Save the resident basic program on disk 

Under the heading, File Access, we will discuss the following statements and 
functions. 



Statements 

OPEN 

CLOSE 

INPUT # 

LINE INPUT# 

PRINT# 

HELD 

GET 

PUT 

LSET 

RSET 

Functions 

CVD 

CVI 
CVS 

EOF 
LOG 



Open a file for access (create the file if necessary) 

Close access to the file 

Read from disk, sequential mode 

Read a line of data, sequential mode 

Write to disk, sequential mode 

Assign field sizes and names to random-access file buffer 

Read from disk, random access mode 

Write to disk, random access mode 

Place value in specified buffer field, add blanks on the 
right to fill field 

Place value in specified buffer field, add blanks on the left 
to fill field 

Restore double-precision number to numeric form after 
GETting from disk 

Restore integer to numeric form after GETting from disk 

Restore single-precision number to numeric form after 
GETting from disk 

Check to see if end of file. encountered during read 

get current record number. 
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lof Return number of last record in file 

mkx>$ Convert double-precision number to string so it can be put 

on disk 

mki$ Convert integer to string so it can be put on disk 

mks$ Convert single-precision number to string so it can be put 

on disk 
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Fie Manipulation 

KILL 

Delete a Fie from the Disk 



msS define a Sile 3pe?:;ysi;<si!i>r> fs r &r f srsilir.? i-(e 



This command works like the trsdos kill command — see trsdos Library 
Commands. 

Example 

KILL"OLDFILE/BAS.PSWi" 

deletes the file specified from the first drive which contains it. 

Do not kill an open file, or you may destroy the contents of the diskette. (First, 
close the open file.) 

LOAD 

Load BASIC Program Fie from Disk 



load exp$ L»J 



This command loads a basic program file into ram; if the r option is used, 
basic will proceed to run the program automatically; otherwise, basic will 
return to the command mode. 
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load without the R option clears all variables and closes all open files, load 
with the R option clears all variables but does not close the open files. 

load with the r option is equivalent to the command run exp$,R. Either of 
these commands can be used inside programs to allow program chaining — one 
program calling another, etc. 

Example 

L0AD"PR0Gi/BAS:2" 

Clears resident basic program and loads progi/bas from Drive 2; returns to 
basic command mode. 

MERGE 

Merge Disk Program with Resident Program 



MERGE expS 

expS is file specification for m Astii-fermai sash: disk fiie. 8.5 . 8 program 
saved with the fi-apiicn. 



merge is similar to load — except that the resident program is not erased before 
the new program exp$ is loaded. Instead, the new program is merged into the 
resident program. 

That is, program lines in exp$ will simply be inserted into the resident program 
in sequential order. If line numbers in exp$ coincide with line numbers in the 
resident program, the resident lines will be replaced by those from exp$. 



■^T^S^EWm^: : r^Eg?~ii^?^r3::rl 
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Program on D 


sk 

+ 


Program in Ram Sferg 


ed Program 




10- ••''; 




10 
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20 


20 




30 


30 




40 


40 




50 


50 




60 


60 




70 


70 




3C 
110 


90 




sc 






: i CO 






i via 






vm 



Sample Use 

Save this program in ascii format. 

1000 REM , , , SUBROUTINE TO SAY HELLO 
1010 PRINT "HELLO! " 
1020 RETURN 

Type NEW (ENTER) , then type in this program. 

100 CLS 

110 PRINT "LET'S CALL THE SUBROUTINE . . ." 

120 PRINT "DIALING NOW , . ." 

130 FOR 1=1 TO 1000 : NEXT 

140 GOSUB 1000 

150 PRINT "BACK FROM SUBROUTINE," 

1G0 END 

Now type HERGE "file" using the hie name given to the first file. List the program. Then ran it. 
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Load and Execute a Program from Disk 



w '.>:> -W ,; 



file is the name ef a iassC program vm %i \% g mtlm %mmmm. m a string 
constat is used, if must be sraiesed In qumm,) Trie s- spllort mmm 

the program Is w%. 



120 



This command loads and executes a basic program stored on disk. It may be 
used inside a program to allow chaining (one program calling another). 

Examples 

RUN "PROG" 

Loads and executes prog (all open files are closed first). 

A*="NEWPR0G" 

RUN A$* R 

Loads and executes newprog (all open files remain open). 



SAVE 

Save Program onto Disk 



M^ v /. ; r ; ,-,: 



,;V 2- HUH St •'■■!:■ iiU f? :*&. :": ;:.Lir: 'u~ -.:. ;.Afr:- :: ^oici 



This command lets you save your basic programs on disk. You can save the 
program in compressed or ascii format. 

Using compressed format takes up less disk space and is faster during both 
saves and loads. Using the ascii option makes it possible to do certain things 
that cannot be done with compressed format basic files. 

For example: 

• The merge command requires that the disk file be in ascii form. 

• Programs which read in other programs as data will typically require that the 
data programs be stored in ascii. 

• The trsdos command append also requires that disk files be in ascii form. 



I; ?: i:r^mr-y* --*'*~: 9~-r* <"■ *■'■ i 
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Examples 

SAME"FILE1/BAS, J0HNQD0E;3" 

saves the resident basic program in compressed format with the fi!e name filei, 
extension /bas, password johnqdoe; the file is placed on Drive :3. 

SAVE"MATHPAK/TXT" »A 

saves the resident program in ascii form, using the name mathpak/txt, on the 
first nonwrite-protected diskette. 

Upon completion of a save, basic returns in the command mode. 

Note: If you try to save a file using the A option (ASCII format), the maximum 
number of characters per line cannot exceed 255 (254 characters and the carriage 
return); otherwise, a DIRECT statement in FILE error will occur. 
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Fie Access 

This section is divided into four parts: 

1 . Creating files and assigning buffers — open and close 

2. Statements and functions 

3. Sequential i/o techniques 

4. Random i/o techniques 

If this is your first experience with disk file access, you should concentrate on 
parts 1 , 3 and 4, perhaps just skimming through part 2 to get a general idea of 
how the functions and statements work. Later you can go back to part 2 and 
learn the details of statement and function syntax. 

Creating Files and Assigning Buffers 

During the initialization dialog, you type in a number in response to how many 
files? The number you type in tells basic how many buffers to create to handle 
your disk accesses (reads and writes). 

Each buffer is given a number from 1 to 15. If you type: 

HOW MANY FILES? 3V (ENTER) 

basic sets aside 3 buffers, numbered 1,2,3. 

You can think of a buffer as a waiting area that data must pass through on the 
way to and from the disk file. When you want to access a particular file, you 
must tell basic which buffer to use in accessing that file. You must also tell 
basic what kind of access you want — sequential output, sequential input, or 
random input/output. 

All this is done with the open statement, and "undone" with the close 
statement. 

OPEN 
Open a Fie 



open mode, buffet, file, record-length 

i ^liusmid! :-rjpu? carting si the frs? ^c-sit, ij #<? &? '* ^- ^'- r,r - 
it will be created. 
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if meae is s constant If miss! m enclosed in quotes, 

fmffer is a numeric expression specifying which Suffer is to m used. 

ffls is a string sspressra santsmmg the file ipeeifiMilon. I! s c-cnstsm is 
ami, i! must he enciossp in poies, 

resarsj-lsngth te a numeric expression from to 268 specifying the logical 
record isnoth. Is the same as 256. This option msy only as used if 

;! '.c...; v.-.;?; :•;-■'■. . r--t: :.-.:',';--: . ■::--: ^^y. ..•*■<.••■ ■.■r3->sit£lh 
Is ussti with Random access fffl%; 



This statement lets you create a file, write data into it, update it, and read it. For 
details on file access, see Methods of Access later in this section. 

If file includes a drive specification, basic will use only the specified drive. If 
no drive is specified, basic will search for a matching file, starting with the 
master drive (usually Drive 0). 

Examples 

OPEN "0" » I t "DATAFILE" 

Opens datafile (creates it if it doesn't already exist) for sequential output. 
Output will be done through buffer #1. Records will be 256 bytes long. Since 
the "o" mode is specified, output will start at the first record in the file. 
If "e" is used instead of "o", output will start at the end of the file. 

OPEN "R" t 2, "PAYROLL/A: 1" , 64 

Opens/creates payroll/a for random input/output. Access will be through 
buffer #2. Records will be 64 bytes long (if basic was initialized for variable- 
length records). 

BUFFER = 3: FILE* = "DATA": RECLN = 128 
OPEN "R" , BUFFER* F!LE$» RECLN 

Opens/creates data for random input/output. Access will be through buffer #3. 
Records will be 128 bytes long (if basic was initialized for variable-length 
records). 



124 



CLOSE 

Close Access to tie Fie 
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This command terminates access to a file through the specified buffer(s). 
If nmexp has not been assigned in a previous open statement, then 

close nmexp 

has no effect. 

Examples 

CLOSE I *2»8 

Terminates the file assignments to buffers 1 , 2 and 8. These buffers can now be 
assigned to other files with open statements. 

CLOSE FIRSU+COUNTX 

Terminates the file assignment to the buffer specified by the sum 
(first% + count%) . 

Do not remove a diskette which contains a file opened for writing (mode = O, 
E, or R). First close the file. This is because the last 256 bytes of data may not 
have been written to disk yet. Closing the file will write the data, if it hasn't 
already been written. 

Any modification to the resident program (new, editing, load, merge, etc.) 
will cause open files to be closed. 
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INPUT# 

Sequential Mead from Disk 



"# nmexp, var\,var, . .] 

wl'seic rrnsx^i spsr.ififci •• ssq»je:>tial hipuiiiie iwfiei. nmexp- 1.2, ...,15. 
raris {hs vsnabft; ngine )o contain the dais from the file, 



This statement inputs data from a disk file. The data is input sequentially. That 
is, when the file is first opened, a pointer is set to the beginning of the file. 
Each time data is input, the pointer advances. To start over reading from the 
beginning of the file, you must close the file and re-open it. 

input# doesn't care how the data was placed on the disk — whether a single 
print# statement put it there, or whether it required 10 different print# 
statements. What matters to input# are the positions of the terminating 
characters and the eof marker. 

To input# data successfully from disk, you need to know ahead of time what 
the format of the data is. Here is a description of how input# interprets the 
various characters it encounters when reading data. 

When inputting data into a variable, basic ignores leading blanks; when the 
first non-blank character is encountered, basic assumes it has encountered the 
beginning of the data item. 

The data item ends when a terminating character is encountered or when a 
terminating condition occurs. The particular terminating characters vary, 
depending on whether basic is inputting to a numeric or string variable. 

Special Note 

Here's an important exception to keep in mind in reading the following material. 

When CEiTEH) (a carriage return) is preceded by © (a line feed), the (ENTER) is 
not taken as a terminator. Instead, it becomes a part of the data item (string 
variable) or is simply ignored (numeric variable). 

(To enter the © character from the keyboard, press the down-arrow character. 
To enter the ( ENTER) character, press (ENTER) .) 

This exception applies to all cases noted below where (ENTER) is said to be a 
terminator. 
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Numeric Input 

Suppose the data image on disk is 

1,23a -33 27 (1WTEW) 
(ENTER) denotes a carriage-return character (ascii code decimal 13). 
Then the statement 
INPUT*! » A»B >C 
or the sequence of statements 
INPUT#1»A; INPUT«l»Bs INPUT#i ,C 
will assign the values as follows: 
A =1.234 
B=-33 
C = 27 

This works because blanks and (ENTER) serve as terminators for input to numeric 
variables. The blank before 1.234 is a "leading blank," therefore it is ignored. 
The blank after 1.234 is a terminator; therefore basic starts inputting the second 
variable at the - character, inputs the number - 33, and takes the next two 
blanks as terminators. The third input begins at the 2 and ends with the 7. 

String Input 

When reading data into a string variable, input ignores all leading blanks; 
the first non-blank character is taken as the beginning of the data item. 

If this first character is a double-quote ("), then input will evaluate the data as 
a quoted string: it will read in all subsequent characters up to the next double- 
quote. Commas, blanks, and (ENTER) characters will be included in the string. 
The quotes themselves do not become a part of the string. 

If the first character of the string item is not a double-quote, then input will 
evaluate the data as an unquoted string: it will read in all subsequent characters 
up to the first comma, or (ENTER) . If double-quotes are encountered, they will be 
included in the string. 

For example, if the data on disk is: 

PECOS, TEXAS"GOQD MELONS" 

Then the statement 

INPUTsl , A*sB$>C$ 



IMWtMsS^S^*? j 
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would assign values as follows: 

A$ = PECOS 

B$= TEXAS "GOOD MELONS" 

C$ = null string 

If a comma is inserted in the data image before the first double quote, c$ will 
get the value, good melons. 

These are very simple examples just to give you an idea of how input works. 
However, there are many other ways to input data — different terminators, 
different target variable types, etc. 

Rather than taking a shotgun approach and trying to cover them all, we'll give a 
generalized description of how input works and what the terminating characters 
and conditions are, and then provide several examples. 

When basic encounters a terminating character, it scans ahead to see how many 
more terminating characters it can include with the first terminator. This ensures 
that basic will begin looking for the next data item at the correct place. 

The list below defines the various terminating sets input# will look for. It will 
always try to take-in the largest set possible. 

Numeric-Input terminator sets 

end of file encountered 

255th data character encountered 

, (comma) 

mm 
(mm & 
t . . .] [ emu ] 

[ . . .] [ dRSH) © ] 

Quoted-string terminator sets 
end of file encountered 
255th data character encountered 
' ' (double quote) 



"[ . 


■ •][,] 


"[ . 


..][(nn®] 


"[ . 


. .][GHTH)® 



Unquoted-string terminator sets 

end of file encountered 

255th data character encountered 

' (EWTER) [©] 

Figure 13 describes how input# assigns data to a variable. 
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EXAMINE NEXT 
CHARACTER 








\l 








..NO 


PUT IT INTO 
TEMPORARY 

SAVE AREA 




EXAMINE NEXT 
CHARACTER 


^^Tsf 




? 


y 





PICKUP THE 
TERMINATOR 

SET 




V 














GET DATA FROM 
TEMPORARY 
SAVE AREA 




EVALUATE IT 


-V 


ASSIGN TO 

VARIABLE 


"5 


END 


■> 







Figure 13. Input process. 

The following table shows how various data images will be read-in by the 
statement: 

INPUT*! >A»B »C 



Ex.# 


Image on disk 


Values 
assigned 


1 


123.45 (IWTEffiW B.ZEi! 70BBMTER) 


A = 123.45 
B = 82000 
C = 7000 


2 


3©(IIII1 4 CElTEffiS flEHTEB) AlZeof 


A = 34 
B = 5 
C = 


3 


i . »2>3>4 (INTER) 


A = 1 

B = 
C = 2 


4 


i »3 » eof 


A=1 

B = 3 

C = eof error 



(eof = end of ile): 

In Example 2 above, why does variable c get the value 0? When the input 
reaches the end of hie, it terminates that last data item, which then contains 
"a 12." This is evaluated by a routine just like the basic val function — which 
returns a zero since the hrst character of "A12" is a non-numeric. 
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In Example 3, when input# goes looking for the second data item, it 
immediately encounters a terminator (the comma); therefore, variable B is given 
the value zero. 

The following table shows how various data images on disk will be read by the 
statement: 

INPUT«1 »A$»B$ 



Ex.# 


Image on disk 


Values assigned 


1 


"ROBERTS * J, "ROBERTS »M,N eof 


A$:ROBERTS,J. 
B$:ROBERTS,M.N. 


2 


ROBERTS »J.» ROBERTS »M,N, (ENTER) 


A$:ROBERTS 
B$:J. 


3 


THE WORD "QUO" ,12345,789 (ENTER) 


A$:THE WORD "QUO" 
B$:1 2345.789 


4 


BYTE© (ENTER) UNIT OF MEMORY eof 


A$:BYTE©ffWTER) 
UNIT OF MEMORY 
B$:nuII (eof error) 



In Example 3, the first data item is an unquoted string, therefore, the double- 
quotes are not terminators, and become part of A$. 

In Example 4, the (ENTER ) is preceded by an ©, therefore it does not terminate 
the first string; both © and (ENTER ) are included in a$. 

LINE INPUT# 

Mead a Line of Text from Disk 



vst$ Is the variable name to contain the string cats. 



Similar to line input from keyboard, this statement reads a "line" of string 
data into var$. This is useful when you want to read an Ascii-format basic 
program file as data, or when you want to read in data without following the 
usual restrictions regarding leading characters and terminators. 
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line input (orLiNEiNPUT — the space Is optional) reads everything from the first 
character up to: 

1 . an CENTER ) character which is not preceded by © 

2. the end of file 

3. the 255th data character (this 255 character is included in the string) 

Other characters encountered — quotes, commas, leading blanks, © (ENTER) 
pairs — are included in the string. 

For example, if the data looks like: 

10 CLEAR 500 (EWTEB) 

20 OPEN" I " .1 > "PROG" (HTER) 



then the statement 
LINEINPUTst jA$ 
could be used repetitively to read each program line, one line at a time. 

PRINT# 

Sequential Write to Disk Fie 



vti':H'i^!msxa-l<M:m m^mi \ ems s?5 .'-. 



This statement writes data sequentially to the specified file. When you first open 
a file for sequential output, a pointer is set to the beginning of the file, therefore 
your first print# places data at the beginning of the file. At the end of each 
print# operation, the pointer advances, so the values are written in sequence. 
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A print# statement creates a disk image similar to what a print to display 
creates on the screen. Remember this, and you'll be able to set up your print'# 
list correctly for access by one or more input statements. 

print# does not compress the data before writing it to disk; it writes an ascii- 
coded image of the data. 

For example, if a = 123.45 

PRINT#1 >A 

will write a nine-byte character sequence onto disk: 

123,45 (INTER) 

The punctuation in the print list is very important. Unquoted commas and semi- 
colons have the same effect as they do in regular print to display statements. 

For example, if a = 2300 and B = 1.303, then 

PRINT#1 »A»B 

places the data on disk as 

2300 1.303 (ENTER) 

The comma between a and b in the print# list causes 10 extra spaces in the 
disk file. Generally you wouldn't want to use up disk space this way, so you 
should use semi-colons instead of commas. 

PRINT*1 ?A5B 

writes the data as: 

2300 1,303 (ENTER) 

print# with numeric data is quite straightforward — just remember to separate 
the items with semi-colons. 

print# with string data requires more care, primarily because you have to insert 
delimiters so the data can be read back correctly. In particular, you must 
separate string items with explicit delimiters if you want to input# them as 
distinct strings. 

For example, suppose: 

A*="J0HN 0, DOE" and B$=" 100-0 1-001" 

Then: 

PRINT»1 t a$;b$ 

would produce this image on disk: 

JOHN Q. DOE100-01-001 (1WTER) 

which could not be input back into two variables. 

The statement: 
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PRINTS! , Mi" f" iB$ 

would produce; 

JOHN 0. DOE* 100-01 -iBi 

which could be input# back Info two variables. 

This method is adequate If the string data contains no delimiters — commas or 
(EMTER) — characters. But if the data does contain delimiters or leading blanks 
that you don't want to Ignore, then you must supply explicit quotes to be written 
along with the data. For example, suppose A$= " DOE » JOHN , " and B$= " IBB 
-01-001" 

if you use 

PRINT*! »A*i" ." 5B* 

the disk image will be: 

DOE. JOHN 0, »!0g-0i-0Bi CtWTETO 

When you try to input this with a statement like 

1NPUT82sA*;B* 

a$ will get the value doe, and b$ will get john q. — because of the comma after 
doe in the disk Image. 

To write this data so that it can be Input correctly, you must use the chr$ 
function to Insert explicit double quotes Into the disk Image. Since 34 is the 
decimal ascii code for double quotes, use chr$(34) as follows: 

PR I NT* 1 .CHR$C34) ?A$?CHR$(345 IB* 

this produces the disk Image 

"DOE. JOHN Q f "iBB-0i-B01 CENTER ) 

which can be read with a simple 

INPUT»2.A*B$ 

Mote: You can also use the chr$ function to insert other delimiters and control 
codes Into the file, for example: 

chr$(10) © Line Feed 

chr$(13) carriage return ( (ENTERl character) 

chr$(1 i) or chr$(12) line-printer top-of-form 

USING Option 

This option makes it easy to write files in a carefully controlled format. 

For example, suppose: 

A*="LUDWIG" 
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B$="VAN" 

C$= "BEETHOVEN" 

Then the statement 

PRINT*1 sUSING" ! . !. % % " 1A* IB* 5C* 

would write the data in nickname form: 

L.M.BEET < ENTER > 

(In this case, we didn't want to add any explicit delimiters.) See the print using 
description in the level ii basic Reference Manual for a complete explanation of 
the field-specifiers. 

Random Access Statements 

FIELD 

Organize a Random File-Buffer Into Fields 



field nmexp.nmexpl t&var1$\,nmexp2 as var2S. , ,] 

nmsxpl specifies the length of the first field. 

var1$ defines a variable name for the first field. 
■•i?zyi!?zcz%-ihi--:\? ■-;>?■£ :-r.::i c .?.i-r.": ?■?• ': 

should Bpai the record length. 



Before FiELDing a buffer, you must use an open statement to assign that buffer 
to a particular disk file (you must use random access mode). Then use the field 
statement to organize a random file buffer so that you can pass data from basic 
to disk storage and vice-versa. 

Each random file buffer has up to 256 bytes which can store data for transfer 
from disk storage to basic or from basic to disk. (When variable-length files are 
used, maximum may be from 1 to 256.) However, you need a way to access this 
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buffer from basic so that you can either read the data it contains or place new 
data in it. The held statement provides the means of access. 

You may use the held statement any number of times to "re-organize" a file 
buffer. FiELDing a buffer does not clear the contents of the buffer; only the 
means of accessing the buffer (the field names) are changed. Furthermore, two 
or more field names can reference the same area of the buffer. 

Examples 

FIELD 1 i 128 AS A$ » 128 AS B$ 

This statement tells basic to assign the first 1 28 bytes of the buffer to the string 
variable a$ and the remaining 128 bytes to b$. If you now print a$ and b$, you 
will see the contents of the buffer. Of course, this value would be meaningless 
unless you have used get to read a 256-byte record from disk. 

Note: All data — both strings and numbers — must be placed into the buffer in 
string form. There are three pairs of functions (mki$/cvi,mks$/cvs.mkd$/cvd) 
for converting numbers to strings and vice- versa. See "Functions" below. 

FIELD 3 > IB AS NM$ , 25 AS AD$ » 10 AS CY* > 2 AS ST$»7 AS ZP$ 

The first 16 bytes of buffer 3 are assigned the buffer name nm$; the next 25, 
ad$; the next 10, cy$; the next 2, st$ and the next 7, zp$. The remaining 196 
bytes of the buffer are not fielded at all. 

More on field names 

Field names, like nm$,ad$,cy$,st$, and zp$, are not string variables in the 
ordinary sense. They do not consume the string space available to basic. 

Instead, they point to the buffer field which you assigned with the field 
statement. That's why you can use: 

100 FIELD 1 »255 AS A$ 

without worrying about whether 255 bytes of string space are available for a$. 

If you use a buffer field name on the left side of an ordinary assignment 
statement, that name will no longer point to the buffer field; therefore, you 
won't be able to access that field using the previous field name. 

For example, 

A$ = B$ 

nullifies the effect of the field statement above (line 100). 

During random input, the get statement places data into the 255-byte buffer, 
where it can be accessed using the field names assigned to that buffer. During 
random output, lset and rset place data into the buffer, so you can then put 
the buffer contents into a disk file. 



is® 
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Often you'll want to use a dummy variable in a field statement to "pass 
over" a portion of the buffer and start fielding it somewhere in the middle. 
For example: 

FIELD 1, IB AS CLIENT*(1)# 112 AS HiSTtCI) 

FIELD I* 128 AS DUMMY* , 16 AS CI JENT*(2 ) , 112 AS HIST$(2) 

In the second field statement, dummy$ serves to move the starting position of 
client$(2) to position 129. In this manner, two identical "subrecords" are 
delned on buffer number 1 . We won't actually use dummy! to place data into 
the buffer or retrieve it from the buffer. 

The buffer now looks like this: 



16 



112 



CL$ 
(1) 



HlST$ 

Ci) 



16 



CL$ 
(2) 



112 



HISIS 
(2) 



DUMMY$ 



GET 

Mead a Record from Disk— Random Access 



yip Br?mm%mmmi) 



fSf|fSl : : »if::1 

feiii:fc : |if:ig 



•lief. 



W8XBH 



lltliffSit: 



This statement gets a data record from a disk file and places it in the specified 
buffer. Before GETting data from a file, you must open the file and assign a 
buffer to it. That is, a statement like: 

open "R" ,ntnexpl filespec 

is required before the statement: 

get nmexpl , nmexpl 

get tells basic to read record nmexpl from the file and place it into the nmexpl 
buffer. If you omit the record number in get, basic will read the current record. 
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The "current record" is the record whose number Is one higher than that of the 
last record accessed. The first time you access a file via a particular buffer, the 
current record is set equal to 1 . 

For example: 

Program statement Effect 

1000 open"R",i,"name/bas" Open name/bas for random access 

using buffer 1 

ioio field i,... Structure buffer 

1020 get i get record 1 into buffer 1 

1025 REM... ACCESS BUFFER 

1030 get 1,30 get record 30 into buffer 1 

1035 REM. ..ACCESS BUFFER 

1040 get 1,25 get record 25 into buffer 1 

1046 REM... ACCESS BUFFER 

1050 geti get record 26 into buffer 1 

If you are using variable-length records (not fixed-length), an attempt to get 
past the end of file will produce an error. 

If you are using fixed-length records, the same attempt will return a null record 
and no error will occur. To prevent this from occurring, you can use the lof 
function to determine the number of the highest numbered record. 

PUT 

Write a Record to Disk— Random Access 



pur nmexpllnmsMfi^l 

r;mexp2 spedf'e? v.^ reca^c ;.iir;^:e' :■; K- ■■ ■■- ::~\6^j % ■:■■: .■;•.•.:; -; yv; 
assumed. 



This statement moves data from a file's buffer into a specified place in the file. 
Before putting data in a file, you must: 

1 . open the file, thereby assigning a buffer and defining the access mode (must 
be r); 
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2, field the buffer, so you can 

3. place data into the buffer with lset and rset statements. 
When basic encounters the statement: 

put nmexp ,nmexp2 
it does the following: 

• Gets the information needed to access the disk hie 

• Checks the access mode for this buffer (must be r) 

• Acquires more disk space for the file if necessary to accommodate the record 
indicated by nmexp2 

9 Copies the buffer contents into the specified record of the disk file 

• Updates the current record number to equal nmexp2 + 1 

The "current record" is the record whose number is one higher than the last 
record accessed. The first time you access a file via a particular buffer, the 
current record is set equal to 1 . 

If the record number you put is higher than the end-of-file record number, then 
nmexp2 becomes the new end-of-file record number. 

LSET and ESET 

Place Data in a Random Buffer Field 



var$ - SMpSmi asm m$~ bmoS 
vgr$i$ s field name. 
sjwf contains tha cats to m pissed In IN buffet fiskj nnrndA ay vas-S. 



These two statements let you place character-string data into fields previously 
set up by a field statement. 

For example, suppose nm$ and ad$ have been defined as field names for a 
random file buffer. nm$ has a length of 18 characters, and ad$ has a length of 
25 characters. 

Now we want to place the following information into the buffer fields so it can 
be written to disk: 
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name: JIM CRICKET > JR. 

address: 2000 EAST PECAN ST, 

This is accomplished with the two statements: 

LSET NM$="JIM CRICKET .JR. " 
LSET AD$="2000 EAST PECAN ST, " 

This puts the data in the buffer as follows: 



JIM CRICKET .JR. 



2000 EAST PECAN ST. 



NM$ 



AD$ 



Note that filler spaces were placed to the right of the data strings in both cases. 
If we had used rset instead of lset statements, the filler spaces would have 
been placed on the left. This is the only difference between lset and rset. 

For example: 

RSET NM$="JIM CRICKET. JR. " 
RSET AD$="2000 EAST PECAN ST. " 

places data in the fields as follows: 



JIM CRICKET .JR. 



2000 EAST PECAN ST. 



NM$ 



AB$ 



If a string item Is too large to fit in the specified buffer field, it is always 
truncated on the right. That is, the extra characters on the right are ignored. 



CVD, C¥I and CVS 

Restore String to Numeric Form 



:• •';■■-■ •:•• ■'• -i^^^i ■■: ; i i!'-w-'; r&-h.- a ■' .^iax^l '■'■. m 
■.:<-.■■■■.■ ,- ■"'v-'-i.li< r 1. : -.^(<»rt: >'-. -:'7 ■'-.■■f; i: it ■■'■'■■:.*■' 
characters are used, 

f\m mmsmm a numeric string. If ukfsxpSh 2, m aiiosi fungtsor 
m\ error occurs; If imisxpS} ■■ I- only the first two characters are 
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sm$ defines n miit^Mnmr sfrma; sAf f is typiGaify the name at a Sniffer 
lisle sorptsiREftg e rsiiSTief-Sc string, if Lik{exp$y-£i s m mmM. rmam 
call srrar occurs: if un(axp$} >A, en>¥ the first four sharasters are 



These functions let you restore data to numeric form after it is read from disk. 
Typically the data has been read by a get statement, and is stored in a random- 
access lie buffer. 

The functions cvd, cvi, and cvs are inverses of mkd$, mki$, and mks$, 
respectively. 

For example, suppose the name grosspays references an eight-byte field in 
a random-access file buffer, and after GETting a record, grosspay$ contains a 
mkd$ representation of the number 13123.38. 

Then the statement: 

PRINT CVD (GROSSPAY*) -TAXES 

prints the result of the difference, 13123.38 -taxes. Whereas the statement: 

PRINT GROSSPAY$-TAXES 

will produce a type mismatch error, since string values cannot be used in 
arithmetic expressions. 

Using the same example, the statement 

A«=CUD( GROSSPAY*) 

assigns the numeric value 13123.38 to the double-precision variable a#. 

EOF 

Eni-Of-FIe Detector 



illifiiiil^ 

/MWAp specifies a fife biiffer, nmexp=*J. ..M, 
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This function checks to see whether all characters up to the end-of-file marker 
have been accessed, so you can avoid input past end errors during sequential 
input. 

Assuming nmexp specifies an open ile, then EOF(nmexp) returns (false) when 
the eof record has not yet been read, and — 1 (true) when it has been read. 



Examples 



IF E0F(5) THEN PRINT"END OF FILE"FILENM$ 
IF E0F(NM%) THEN CLOSE NM% 

The following sequence of lines reads numeric data from data/txt into the 
array a( ). When the last data character in the hie is read, the eof test in line 
30 "passes," so the program branches out of the disk access loop, preventing 
an input past end error from occurring. Also note that the variable i contains 
the number of elements input into array a( ) . 

5 DIM AU00) 'ASSUMING THIS IS A SAFE VALUE 

10 OPEN "I" ,1 , "DATA/TXT" 

20 11=0 

30 IF EOF(l) THEN 70 

M INPUT*! .Ad*.) 

58 I % = I % + 1 

60 GOTO 30 

70 REM PROGRAM CONTINUES HERE AFTER DISK INPUT 



LOC 

Get Current Mecori Number 



tile um&ti! -i % mx.mvj, iim^th;, s&i^ifymu trsfe M;r&r !o- *§ ea^nify- 



loc is used to determine the current record number, i.e., the number of the last 
record read since the file was opened, loc is only valid after a get. 

Example 

PRINT LOC(l) 
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Sample Program 

1310 A$ = "WILLIAM WILSON" 

1320 GET 1 j X: X=K+1 

1330 IF N$ = A$ THEN PRINT "FOUND IN RECORD" LOC(i): CLOSE: 

END 
1340 GOTO 1320 

This is a portion of a program. Elsewhere the file has been opened and fielded. 
n$ is a field variable. If n$ matches a$ the record number in which it was found 
is printed. 

LOF 

Get End-Of-Fie Record Number 






This function tells you the number of the last, i.e., highest numbered, record 
in a file. It is useful for both sequential and random access. 

For example, during random access to a pre-existing file, you often need a 
way to know when you've read the last valid record, lof provides a way. 

lof is valid as soon as a previously created file is opened. If a file is extended, 
lof is not valid until a get is executed. 

Examples: 

10 OPEN "R" ,1 ("UNKNOWN/TXT" 
20 FIELD 1 (255 AS A$ 
30 F0RIX=1 TO L0F(1) 
40 GET 1 >I1 

50 PRINT A$ 
60 NEXT 

In line 30, LOF(i) specifies the highest record number to be accessed. 

Note: If you attempt to get record numbers beyond the end-of-file record, basic 
simply fills the buffer with hexadecimal zeros, and no error is generated. 
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When you want to add to the end of a file, lof tells you where to start adding: 

100 I%=L0F(i)+i 'HIGHEST EXISTING RECORD 
110 PUT i.II 'ADD NEXT RECORD 

MKD$, MKI$, and MKS$ 
Convert Data, Numeric-to-String 



nmexp is evaluated as a doabie-pirscislop nyrnoer- 
fractional component in nmexp Is truncaled. 



These functions change a number to a "string." Actually the byte values which 
make up the number are not changed; only one byte, the internal data-type 
specifier, is changed, so that numeric data can be placed in a string variable. 



That is: 



mkds returns an eight-byte string. 
mki$ returns a two-byte string. 
mks$ returns a four-byte string. 



Examples 

LSET TALLY$=MKI$(I%) 

Field name tallys would now contain a two-byte representation of the 
integer i%. 

A*=MKI*(8/I> 



rKS:byf¥mi T ^i^r~T'::,; . ..;.:.::.•...:_ ..." . . ■- 
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a$ becomes a two-byte representation of the Integer portion of 8/1. Any 
fractional portion is ignored. Note that a$ in this case is a normal string 
variable, not a buffer-field name. 

Suppose baseball/bat (a non-standard lie extension) has been opened for 
random access using buffer 2, and the buffer has been FiELDed as follows: 



held: 


NM$ 


YRS$ 


AVG$ 


HR$ 


AB$ 


ERNING$ 


length: 


16 


2 


4 


2 


4 


4 



nm$ is intended to hold a character string; avg$, ab$ and ernings, converted 
single-precision values; yrs$ and hr$, converted integers. 

Suppose we want to write the following data record: 

slow learner played 38 years; lifetime batting average . 123; 
career homeruns, 11; at bats, 32768;..., earnings - 13.75. 

Then we'd use the make-string functions as follows: 



1000 


LSET 


NM$="SL0W LEARNER" 


1010 


LSET 


YRS$=MKI*(38) 


1020 


LSET 


AMG$=MKS$( ,123) 


1030 


LSET 


HR$=MKI$(11) 


1040 


LSET 


AB$=HKS$(327G8) 


105B 


LSET 


ERNING*=MKS*(-13,75) 



After this sequence, you can write slow learner's information to disk with 
the put statement. When you read it back from disk with get, you will need 
to restore the numeric data from string to numeric form, using cvi and cvs 
functions. 
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Disk basic provides two means of ile access: 

• Sequential — in which you start reading or writing data at the beginning of 
a file; subsequent reads or writes are done at following positions in the ile. 

• Random — in which you start reading or writing at any record you specify. 
(Random access is also called direct access.) 

Sequential access is stream-oriented; that is, the number of characters read or 
written can vary, and is usually determined by delimiters in the data. Random 
access is record-oriented; that is, data is always read or written in fixed- length 
blocks called records. 

To do any input/output to a disk file, you must first open the file. When you 
open the file, you specify what kind of access you want: 

• o for sequential output 

• i for sequential input 

• R for random input/output 

• e (Extend) for sequential output starting at the end of file. 

You also assign a file buffer for basic to use during file accesses. This number 
can be from 1 to 15, but must not exceed the number of concurrent files you 
requested when you started basic from trsdos. For example, if you started 
basic with 3 files, you can use buffer numbers 1,2, and 3. Once you assign a 
buffer number to a file, you cannot assign that number to another file until you 
Close the first file. 

Examples 

OPEN "0" > if "TEST" 

Creates a sequential output file named test on the first available drive; if test 
already exists, its previous contents are lost. Buffer 1 will be used for this file. 



Opens test for sequential input, using buffer 2. 

OPEN "R" » I; "TEST" 

Opens test for direct access, using buffer 1 . If test does not exist, it will be 
created on the first available drive. Since record length is not specified, 256-byte 
records will be used. 

OPEN "R" t If "TEST" , 40 

Same as preceding example, but 40-byte records will be used. 

OPEN "E" t If "TEST" 

Opens test sequentially for write and positions to eof. 
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Sequential Access 



This is the simplest way to store data in and retrieve it from a file. It is ideal for 
storing free-form data without wasting space between data items. You read the 
items back in the same order in which they were written. 

There are several important points to keep in mind. 

1 . You must start writing at the beginning of the file. If the data you are seeking 
is somewhere inside, you have to read your way up to it. 

2. Each time you Open a file for sequential output, the file's previous contents 
are lost, unless you use "E" instead of "O" for the mode. 

3. To update (change) a sequential file, read in the file and write out the updated 
data to a new output file. 

4. Data written sequentially usually includes delimiters (markers) to signify 
where each data item begins and ends. To read a file sequentially, you must 
know ahead of time the format of the data. For example: Does the file consist 
of lines of text terminated with carriage returns? Does it consist of numbers 
separated by blank spaces? Does it consist of alternating text and numeric 
information? 

5. Sequential files are always written as Ascn-coded text, one byte for each 
character of data. For example, the number: 

1.2345 

requires 8 bytes of disk storage, including the leading and trailing blanks that 
are supplied. The text string: 

JOHNSON f ROBERT 

requires 15 bytes of disk storage. 

6. Sequential files are always written with a record length of 256. 



Sequential Output: Am Example 

Suppose we want to store a table of English-to-metric conversion constants: 



English unit 


Metric equiwalent 


1 inch 


2.54001 centimeters 


1 mile 


1 .60935 kilometers 


t- acre 


4048.86 sq. meters 


1 cubic inch 


0.01638716 liter 


1 U.S. gallon 


3.785 liters 


1 liquid quart 


0.9463 liter 


1 lb (avoir) 


0.45359 kilogram 
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First we decide what the data image is going to be. Let's say we want it to look 

like this: 

english unit | metric unit, factor (ENTER) 

For example, the stored data would start out: 

IN->CM» 2.54001 (INTER) 

The following program will create such a data file. 

Note: X'OD' represents a carriage return. 

10 OPEN "0" >l »" METRIC/TXT" 

20 FOR I%=1 TO 7 

30 READ UNIT** FACTR 

40 PRINT*1 t UNIT*I " »"» FACTR 

50 NEXT 

G0 CLOSE 

70 DATA IN->CMj 2,54001s MI->KM> 1,60935* ACRE->SQ.KM » 

4046,86 E-E 
80 DATA CU.IN->LTR> 1.G3871GE-2. GAL->LTR» 3,785 
90 DATA LIQ,QT->LTR» 0,9463* LB->KGt 0,45359 

Line 10 creates a disk file named metric/txt, and assigns buffer 1 for sequential 
output to that file. The extension /txt is used because sequential output always 
stores the data as Ascn-coded text. 

Note: If metric/txt already exists, line 10 will cause all its data to be lost. 
Here's why: Whenever a file is opened for sequential output, the end-of-file 
(eof) is set to the beginning of the file. In effect, trsdos "forgets" that 
anything has ever been written beyond this point. To avoid this, you could use e 
instead of o in line 10. 

Line 40 prints the current contents of units and factr to the file. Since the 
spring items do not contain delimiters, it is not necessary to print explicit quotes 
around them. The explicit comma is sufficient. 

Line 60 closes the file. The eof is at the end of the last data item, i.e., 0.45359, 
so that later, during Input, basic will know when it has read all the data. 

Sequential Input: An Example 

The following program reads the data from metric/txt Into two "parallel" 
arrays, then asks you to enter a conversion problem. 

5 CLEAR 500 

10 DIM UNIT$C9)* FACTRC9) 'allows for up to 10 data pairs 

20 0PEN"I" >1 »"METRIC/TXT" 

25 IX=0 

30 IF E0F(1) THEN 70 

40 INPUT*1* UNIT$UI> »FACTRIIX) 



wmmmm^mm>km«fmi 
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50 11=11+1 

60 GOTp 30 

70 CLOSE ' Conversion factors have been read-in 

100 CLS: PRINT TAB(5)"**# English to Metric Conversions ***" 

110 FOR ITEM%=0 TO II- 1 

120 PRINT TABC9) !USING"(»# ) I X "UTEM%» 

UNIT*(ITEM%) 
130 NEXT 

140 PRINT @ 704 j "Which conversion (0-6) "5 
150 INPUT CHOICE! 

1G0 INPUT "Enter English quantity" IU 

170 PRINT"The Metric equivalent is" M*FACTR(CHOICE%) 
180 INPUT"Press <ENTER> to continue" 5X 
190 PRINT @ 704 , CHR$(31) 'clear to end of frame 
200 GOTO 140 

Line 20 opens the file for sequential input, input begins at the beginning of 
the file. 

Line 30 checks to see that the end-of-file record hasn't been reached. If it has, 
control branches from the disk input loop to the part of the program that uses 
the newly acquired data. 

Line 40 reads a value into the string array unit$( ), and a number into the 
single-precision array factr( ). Note that this input list parallels the print# list 
that created the data file (see the section "Sequential Output: An Example"). 
This parallelism is not required, however. We could just as successfully have 
used: 

40 INPUTslt UNIT$(I%); INPUT*! »FACTR ( 1% ) 



How to update a lie 

Suppose you want to add more entries into the English- Metric conversion file. 
You could simply re-Open the file with mode = e and print# the extra data. 
Or, you might want to leave the old file intact and output a new file: 

1 . Open the file for sequential input (Mode = i) 

2. Open another new data file for sequential output (Mode = o) 

3. Input a block of data and update the data as necessary 

4. Output the data to the new file 

5. Repeat steps 3 and 4 until all data has been read, updated, and output to the 
new file; then go to step 6 

6. Close both files 
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Sequential Lime Input: An Example 

Using the line-oriented input, you can write programs that edit other basic 
program files: renumber them, change lprints to prints, etc. — as long as these 
"target" programs are stored in ascii format. 

The following program counts the number of lines in any ascii — format basic 
disk file with the extension /txt. 

10 CLEAR 300 

20 INPUT"WHAT IS THE NAHE OF THE PROGRAM" 5 PROG* 

30 IF INSTR(PROG$»"/TXT")=0 THEN 110 'require /TXT extension 

40 OPEN"!" , 1 » PROG* 

50 11=0 

G0 IF EOF(l) THEN 90 

70 I % = 1 % + i : LINE INPUT»1» TEHP$ 

80 GOTO B8 

98 PRINT PROG*" IS" 1% "LINES LONG," 

100 CLOSE: GOTO 20 

110 PRINT "FILESPEC MUST INCLUDE THE EXTENSION '/TXT'" 

120 GOTO 20 

For basic programs stored in ascii, each program line ends with a carriage 
return character not preceded by a line feed. So the line input in line 70 
automatically reads one entire line at a time, into the variable temps. Variable 
i% actually does the counting. 

To try out the program, first save any basic program using the a (ascii) option 
(See save) . Use the extension /txt. 
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Random Access Techniques 

Random access offers several advantages over sequential access: 

• Instead of having to start reading at the beginning of a file, you can read any 
record you specify. 

8 To update a file, you don't have to read in the entire file, update the data, and 
write it out again. You can rewrite or add to any record you choose, without 
having to go through any of the other records. 

8 Random access is more efficient — data takes up less space and is read and 
written faster. 

" Opening a file for direct access allows you to write and read from the file via 
the same buffer. 

• Random access provides many powerful statements and functions to structure 
your data. Once you have set up the structure, direct input/output becomes 
quite simple. 

The last advantage listed above is also the "hard part" of direct access. It takes 
a little extra thought. 

For the purposes of direct access, you can think of a disk file as a set of boxes 
— like a wall of post-office boxes. Just like the post office receptacles, the file 
boxes are numbered. We call these boxes "records." 

You can place data in any record, or read the contents of any record, with 
statements like: 

PUT 1 »5 write buffer- 1 contents to record 5 

GET 1 » 5 read the contents of record 5 into buffer- 1 

In Figure 14, we assume a record length of 256. 
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RECORDS IN DISK FILE 

Figure 14. get and put. 
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The buffer is a waiting area for the data. Before writing data to a file, you must 
place it in the buffer assigned to the file. After reading data from a file, you 
must retrieve it from the buffer. 

As you can see from the sample put and get statements above, data is passed to 
and from the disk in records. The size of each record is determined by an Open 
statement. 

Storing Data In a Buffer 

You must place the entire record into the buffer before putting its contents into 
the disk file. 

This is accomplished by 1) dividing the buffer up into fields and naming them, 
then 2) placing the string or numeric data into the fields. 

For example, suppose we want to store a glossary on disk. Each record will 
consist of a word followed by its definition. We start with: 

100 0PEN"R"» 1> "GLOSSARY/BAB" 

110 FIELD 1, IB AS WD$t 240 AS MEANING* 

Line 100 opens a file named glossary/bas (creates it if it doesn't already exist); 
and gives buffer 1 direct access to the file. 

Line 110 defines two fields onto buffer 1: 

wd$ consists of the first 16 bytes of the buffer; 

meanings consists of the last 240 bytes. 

wd$ and meanings are now field-names 

What makes field names different? Most string variables point to an area in 
memory called the string space. This is where the value of the string is stored. 

Field names, on the other hand, point to the buffer area assigned in the held 
statement. So, for example, the statement: 

10 PRINT WD*5 ":" i MEANING* 

displays the contents of the two buffer fields defined above. 

These values are meaningless unless we first place data in the buffer, lset, rset 
and get can all be used to accomplish this function. We'll start with lset and 
rset, which are used in preparation for disk output. 

Our first entry is the word "left-justify" followed by its definition. 

100 0PEN"R"» 1» "GLOSSARY/BAS" 

110 FIELD 1» IS AS WD*, 240 AS MEANING* 

120 LSET WD*="LEFT-JUSTIFY" 

130 LSET MEANING*="T0 PLACE A VALUE IN A FIELD FROM LEFT TO 
RIGHT1 IF THE DATA DOESN'T FILL THE FIELD, BLANKS ARE 
ADDED ON THE RIGHT? IF THE DATA IS TOO LONG, THE EXTRA 
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CHARACTERS ON THE RIGHT ARE IGNORED. LSET IS A LEFT- 
JUSTIFY FUNCTION," 

Line 120 left-justifies the value in quotes into the first field in buffer 1. Line 130 
does the same thing to its quoted string. 

Note: rset would place filler-blanks to the left of the item. Truncation would 
still be on the right. 

Now that the data is in the buffer, we can write it to disk with a simple put 
statement: 

140 PUT 1 >l 
150 CLOSE 

This writes the first record into the file gloss ary/b as. 

To read and print the first record in glossary/bas, use the following sequence: 

1B0 0PEN"R"» 1* "GLOSSARY/BAS" 

170 FIELD Is IS AS WD$ , 240 AS MEANING$ 

180 GET 1 »1 

180 PRINT WDS; PRINT MEANING$ 

200 CLOSE 

Line 160 and 170 are required only because we closed the file in line 150. If we 
hadn't closed it, we could go directly to line 180. 
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Random Access: A General 
Procedure 

The previous example shows the necessary sequences to read and write using 
random access. But it does not demonstrate the primary advantages of this form 
of access — in particular, it doesn't show how to update existing files by going 
directly to the desired record. 

The program below, glossacc/bas, develops the glossary example to show 
some of the techniques of random access for file maintenance. But before 
looking at the program, study this general procedure for creating and 
maintaining files via random access. 



Step 


See GLOSSACC/BAS, 


Line Number 


1. Open the file 


110 


2. Field the buffer 


120 


3. Get the record to be updated 


140 


4. Display current contents of the record (use 


145-170 


CVD, CVl, CVS before displaying numeric 




data) 




5. LSET and RSET new values into the fields 


210-230 


(use MKD$, MKI$, MKS$ with numeric data 




before setting it into the buffer) 




6. PUT the updated record 


240 


7. To update another record, continue at step 3. 


250-260 


Otherwise, go to step 8. 




8. Close the file 


270 



10 REM .,,,.. GLOSSACC/BAS . ,. 

100 CLS : CLEAR 300 

110 OPEN "R"» 1. "GL0SSARY/BAS" 

120 FIELD 1» IB AS WD* , 238 AS MEANING** 2 AS NX* 

130 INPUT "WHAT RECORD DO YOU WANT TO ACCESS' 1 ! R% 

140 GET 1 , RI 

145 HXl = GUI (NX*) 'SAVE LINK TO NEXT ALPHABETICAL ENTRY 

150 PRINT "WORD ; "WD$ 

160 PRINT "DEF'N : " ; PRINT MEANING* 

170 PRINT "NEXT ALPHABETICAL ENTRY; RECORD »:" NX! : PRINT 

180 W$ = "" : INPUT "TYPE NEW WORD <ENTER> OR <ENTER> IF OK" 5 

W* 
190 D* = "" ; PRINT "TYPE NEW DEF'N < ENTER > OR <ENTER> IF 

OK?" ; LINE INPUT D$ 
200 INPUT "TYPE NEW SEQUENCE NUMBER OR <ENTER> IF OK"? NXI 
210 IF W$ <> "" THEN LSET WD* = W* 
220 IF D* <> "" THEN LSET MEANING* = D$ 
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230 LSET NX$ = MKI* (NXX) 

240 PUT I > Rl 

245 R% = NX% 'USE NEXT ALPHA, LINK AS DEFAULT FOR NEXT RECORD 

250 CLS : PRINT " TYPE <ENTER> TO READ NEXT ALPHA, ENTRY*"; 

PRINT" OR RECORD « <ENTER> FOR SPECIFIC ENTRY*": INPUT " 

OR < ENTER) TO QUIT'S RI 
260 IF 0<R% THEN 140 
270 CLOSE 
280 END 

Notice we've added a field, nx$, to the record (line 120). nx$ will contain the 
number of the record which comes next in alphabetical sequence. This enables 
us to proceed alphabetically through the glossary, provided we know which 
record contains the entry which should come first. 

For example, suppose the glossary contains: 



record# 


word (WD$) 


defn, 


pointer to next 
alpha, entry (NX$) 


1 
2 
3 
4 


LEFT-JUSTIFY 
BYTE 

RIGHT-JUSTIFY 
HEXADECIMAL 




3 
4 

1 



When we read record 2 (byte), it tells us that record 4 (hexadecimal) is next, 
which then tells us record 1 (left- justify) is next, etc. The last entry, record 3 
(right- justify), points us to zero, which we take to mean "The End." 

Since nx$ will contain an integer, we have to first convert that number to a two- 
byte string representation, using mki$ (line 230 above). 

The following program displays the glossary in alphabetical sequence: 

3BB REM ,,, GL0SS0UT/BAS ,,, 

31B CLS : CLEAR 300 

320 OPEN "R" t 1, "GLOSSARY/BAS" 

330 FIELD I* IB AS WD$ , 238 AS MEANING* » 2 AS NX* 

340 INPUT "WHICH RECORD IS FIRST ALPHABETICALLY"; HI 

351 GET 1 t NX 

360 PRINT : PRINT WD$ 

370 PRINT MEANING* 

38i NX = CM I (NX*) 

388 INPUT "PRESS <ENTER> TO CONTINUE"? X 

400 IF NX <> THEN 350 

410 CLOSE 

421 END 



i..-* - .-.-; f-H>^%-^"^frA;;*--Vi 
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Disk BASIC Error Codes/Messages 



r — it 



51 


Field overflow 


52 


Internal error 


53 


Bad file number 


54 


File not found 


55 


Bad file mode 


58 


Disk i/o error 


62 


Disk full 


63 


Input past end 


64 


Bad record number 


65 


Bad file name 


67 


Direct statement in file 


68 


Too many files 


69 


Disk write-protect 


70 


File access 



Note: Disk errors cannot be simulated via the error statement. 
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Appendix A / Tips On Loading Disk basic 

There are several ways to start up Disk BASIC. For instance: 

Bm^h urogram -rltles m. address 

i--~i. !■■:■ : : '.-. ^u.^it- e^y^;*.:^ .■■.. ■■■ ;Y>,:; y^ : ;'. ik^-d 

S A^ • -If r;7^V^i^^Wi*|; •;":',;;;'. Y;.- >V.7> : \V ^Sy-Y^y^yO, >/;Y 
:■ ./^.vYY ■;■::;• ■;; ,V ■■ ■-. w\ ;-Y:Y! : C-YI-P. (V: :Y'-: : V'il ;V>i- ■>■ 

open at ejrie time, flleu is a number front to 15, Tills is 

-^v.-* vi-'-i ■ 'YS ; s^Y'ii Ys?;Yr;; i. sKji f/^j; s.hestMifc 
fi/es wis! be Fixed length. 

••■:.-;.•;- Y ;.'.-'■■■ : Y.-'Y.t*Y " : ',. ;,:y -;-Y^. ;•£>.•;. vt'";^ i; -Y { Y.- 

memory up to Top 

If all options are omitted , Disk BASIC will prompt with HOW MANY FILES? and 
MEMORY? 

The options allow you to specify any or all of the following: 

• A program to run after Disk BASIC is started. 

• The maximum number of data files that may be Open at one time. The larger the 
number of files, the less area available for storing and executing your programs. 
(Note: Each Fixed length file takes up 360 bytes and each Variable length file 
takes up 6 1 6 bytes of memory . ) 

• The highest address to be used by Disk BASIC during program execution . Omit 
this unless you are going to call machine-language subroutines. 

Examples 

Under TRSDOS READY, if you type: 

BASIC (ENTER) , Disk BASIC will enter the command mode once you answer 
the files and memory prompts . 

BASIC -F: 1 CiilM), Disk BASIC will Open one fixed length file and 
protect no memory. 

BASIC - M : 32000 (HTH), Disk BASIC will Open three fixed length files 
and will use memory no higher than 32000. 

BASIC PAYROLL -F : 3M dRQH), Disk BASIC will start-up, then load and 
run the BASIC program called PAYROLL; three variable length files can be 
Opened, and BASIC can use all available memory. 

Note: If you PATCH Disk BASIC to prompt you for cassette speed when you enter 
Disk BASIC , you wil 1 still be prompted with C A S S ? no matter which option you 
use. 
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Sybject Rage 

Abbreviate 14 

APPEND 26 

ASCI! 26, 53 

ATTRIB 10, 24, 27, 80 

AUTO 29, 72 

BACKUP 8,25,57,67 

BASIC 17 

BASIC* 91 

Baud 12, 62 

Bits i, 62 

BKSPC 82 

(HUB 29, 31 , 44, 96 

Buffer 91, 123 

BUILD 29,31,45,57 

Byte i, 18, 62, 74 

Cable (Ribbon) 1,2 

Cass? 12 

CLEAR 31 , 32, 45, 72 

CLOCK 33 

CLOSE 125 

CLOAD 63 

CLS 33 

CMD"A" 93, 95 

CMD"B" 93, 96 

CMD"C" 93, 96 

CMD"D" 93, 97 

CMD"E" 93, 98 

CMD'i" 93, 98 

CMD"J" 93, 99 

CMD"L" 93, 100 

CMD"0" 93, 101 

CMD"P" 93, 102 

CMD"R" 93, 103 

CMD"S" 93, 103 

CMD'T" 93, 104 

CMD"X" 93, 104 

CMD"Z" 93, 105 

Commands 

Auto 29-30 

Entering 20 

Forms of 21 



Sybject Page 

Library 26-66 

Syntax 20 

Utility 67-89 

CONVERT 8, 10, 25, 68 

COPY 34, 50 

CREATE 35 

CSAVE 63 

CVD, CVi, CVS 139-40 

Data Diskette See Diskette 

DATE 36, 37 

DCB 76 

DEBUG 37 

DEFFN 93, 106 

Definitions 

Comments 21-2 

Delimiter 22 

Filename 21-2 

Options 22 

DEF USR 93, 108 

DIR 25,27,44 

Disk BASIC 

Abbreviations 95 

Instructions 11,12 

Starting 11,91-2 

Disk Drive 

Oand 1 1,4, 6, 10, 34, 55 

2, 3 (External) 1,4 

Expansion 1,4 

Installation 1,4 

Diskette 

Care 5 

Data i, 24 

Description 5 

Inserting 5, 7 

Labelling 6 

Notch-protect 5 

Organization 74 

Specifications 15 

System i, 6, 24 

DIVIDE 83 

DMULT 84 

DO 31 , 32, 46, 57, 71 

Drive Specification 23 

DUAL 47 

DUMP 48,54,59 
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Subject Page 

EOF (End-of-file) 45, 75, 1 40-1 

ERROR 49 

Error 13 

DiskBASIC 155 

TRSDOS 90 

Extents See Technical Information 

FIELD 134-6 

File 

Access 116, 123, 145 

APPEND 26 

COPY 34 

Manipulation ".'.'.'.'. '.'. '.'. '.'.'.'.....'... 1 16', 1 18 

System vs User 25 

Variable Length 91 

Filename 23, 44 

File Specification 22 

FILPTR 85 

FORMAT 8,9,25,70 

FORMS 49 

FREE 35, 50 

GET 136-7 

Granules 

Allocation 50 

Defined 74 

Number of 45, 51 , 74 

HELP 51,53 

HERZ50 71 

Hexadecimal 32, 38, 41 , 48, 53 

55, 59, 93, 94 

INIT 78 

INPUT # 126-30 

Installation 1-3 

INSTR 93, 108 

I/O 32, 61 

I/O Calls 75, 77-89 

KILL 52,118 

LSET 138-9 

LIB 53 

LINE INPUT 110,93 

LINE INPUT # 130-1 

LIST 53 

LOAD 12, 54, 118 

Load 11 

LOG 141-2 

LOF 142 

LPC 71 

Maintenance 13 

MASTER 55, 64 

Memory 

Display 38 

Map 19 

User 38, 59 



Subject Page 

Memory Size? 11 

MEMTEST 72 

MERGE 119 

MID$ 93, 111 

MKD$, MKI$, MKS$ 143-4 

NAME 93, 112 

NEW 11 

Notations/Abbreviations 14 

Octal 93, 94 

OPEN 123,4 

Operation 4 

Password 8, 24, 25, 27 

57, 60, 67, 69 

Access 27 

Changing 27 

Master 9, 25 

Protecting 69 

Update 27 

PATCH 12,55 

PAUSE 56 

POSEOF 82 

POSN 79 

Power On/Off 4, 30 

PRINT # 131-3 

Printer 31,47, 105 

Programming ii, 1 1 

PROT 10,25,57 

PURGE 25, 58 

PUT 137-8 

PUTEXT 81 

RAM 18, 32, 40, 64, 71 , 73 

RAMDIR 84 

Random File Access 1 50-4 

General Procedure 1 53 

Techniques 1 50 

READ 70 

Record Length 35, 45 

Logical Length 26, 35, 45, 76 

Number of 45, 77 

Physical 77 

RELO 59 

RENAME 35, 60 

Reset 30, 73 

Location 4 

REWIND 82 

ROM 73 

ROUTE 47, 61 

RSET 138-9 

RS-232-C 62 

RUN 120 

SAVE 11,121 
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Subject __ Pa g# 

Save 11 

Sector 77 

SETCOM 62 

Sequential File Access 146-149 

Sequential Input 1 47 

Sequential Line Input 149 

Sequential Output 146 

Starting 

Auto 29 

DiskBASIC 11 

System 6 

TRSDOS 7 

Specifications 15 

System Diskette See "Diskette" 

Syntax 83 

TAPE 63 

TIME 64 

Troubleshooting 7,13 

TRSDOS 

Definition 17-19 

Start-up 7 

Using 20 

USING 133-4 

USRn 93,113 

VERF 81 

Videooutput 47, 105 

WP 65 

WRITE 80-1 

Write-protect notch 5 

XFERSYS 73 

Z-80 37, 39, 40, 41 , 48 

55, 56, 63 

&Hand&0 93-4 



Subject Page 

Figures and Tables 

A Diskette 5 

Connection of the External Disk Cable 

to the Model III 2 

Connection of External Disk Drives 3 

Directory Listing (dir) 45 

External Disk Cable with 

Plugs Labeled 2 

Free Map (free) 51 

Full-Screen Format (debug) 43 

get and put 1 50 

Half-Screen Format (debug) 40 

Input Process (input) 1 29 

Inserting a Diskette 7 

Model 111 Disk System 

with External Drives 4 

trsdos Memory Map 19 

trsdos Roles 19 
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Eaiio Shack Software License 

The following are the terms and conditions of the Radio Shack Software License for 
copies of Radio Shack software either purchased by the customer, or received with 
or as part of hardware purchased by customer: 

A. Radio Shack grants to CUSTOMER a personal, non-exclusive, paid up license to 
use the Radio Shack computer software programs received. Title to the media 
on which the software is recorded (cassette and/ordisk) or stored (ROM) is 
transferred to the CUSTOMER, but not title to the software. 

B. In consideration for this license. CUSTOMER shall not reproduce copies of such 
software programs except to produce the number of copies required for 
personal use by CUSTOMER (if the software allows a backup copy to be made), 
and to include Radio Shack's copyright notice on all copies of programs 
reproduced in whole or in part. 

C. CUSTOMER may resell Radio Shack's system and applications software 
(modified or not. in whole or in part), provided CUSTOMER has purchased one 
copy of the software for each one resold. The provisions of this Software 
License (paragraphs A, B, and C) shall also be applicable to third parties 
purchasing such software from CUSTOMER. 



Important Mote 



Ail Radio Shack computer programs are licensed on an "as Is" basis without 
warranty. 

Radio Shack shall have no liability or responsibility to customer or any other person 
or entity with respect to any liability, loss or damage caused or alleged to be caused 
directly or indirectly by computer equipment or programs sold by Radio Shack, 
including but not limited to any interruption of service, loss of business or 
anticipatory profits or consequential damages resulting from the use or operation of 
such computer or computer programs. 

Good data processing procedure dictates that the user test the program, run and test 
sample sets of data, and run the system in parallel with the system previously in use 
for a period of time adequate to insure that results of operation of the computer or 
program are satisfactory. 
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Service Policy 



Radio Shack's nationwide network of service facilities provides quick, convenient, 
and reliable repair services for all of its computer products, in most instances. 
Warranty service will be performed in accordance with Radio Shack's Limited 
Warranty. Non-warranty service will be provided at reasonable parts and labor 
costs. 

Because of the sensitivity of computer equipment, and the problems which can 
result from improper servicing, the following limitations also apply to the services 
offered by Radio Shack: 

1 . If any of the warranty seals on any Radio Shack computer products are broken, 
Radio Shack reserves the right to refuse to service the equipment or to void any 
remaining warranty on the equipment. 

2. If any Radio Shack computer equipment has been modified so that it is not 
within manufacturer's specifications, including, but not limited to, the 
installation of any non-Radio Shack parts, components, or replacement boards, 
then Radio Shack reserves the right to refuse to service the equipment, void any 
remaining warranty, remove and replace any non-Radio Shack part found in the 
equipment, and perform whatever modifications are necessary to return the 
equipment to original factory manufacturer's specifications. 

3. The cost for the labor and parts required to return the Radio Shack computer 
equipment to original manufacturer's specifications will be charged to the 
customer in addition to the normal repair charge. 
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IMPORTANT NOTICE 

ALL RADIO SHACK COMPUTER PROGRAMS ARE LICENSED ON AN 
"AS IS" BASIS WITHOUT WARRANTY. 

Radio Shack shall have no liability or responsibiiity to customer or any 
other person or entity with respect to any liability, loss or damage caused 
or alleged to be caused directly or indirectly by computer equipment or 
programs sold by Radio Shack, including but not limited to any interrup- 
tion of service, loss of business or anticipatory profits or consequential 
damages resulting from the use or operation of such computer or 
computer programs. 

NOTE: Good data processing procedure dictates that the user test the 
program, run and test sample sets of data, and run the system in 
parallel with the system previously in use for a period of time 
adequate to insure that results of operation of the computer or 
program are satisfactory. 

RADIO SHACK SOFTWARE LICENSE 

A. Radio Shack grants to CUSTOMER a non-exclusive, paid up license to 
use on CUSTOMER'S computer the Radio Shack computer software 
received. Title to the media on which the software is recorded (cassette 
and/or disk) or stored (ROM) is transferred to the CUSTOMER, but not 
title to the software. 

B. In consideration for this license, CUSTOMER shall not reproduce 
copies of Radio Shack software except to reproduce the number of copies 
required for use on CUSTOMER'S computer (if the software allows a 
backup copy to be made), and shall include Radio Shack's copyright 
notice on ail copies of software reproduced in whole or in part. 

C. CUSTOMER may resell Radio Shack's system and applications soft- 
ware (modified or not, in whole or in part), provided CUSTOMER has 
purchased one copy of the software for each one resold. The provisions 
of this software License (paragraphs A, B, and C) shall also be applicable 
to third parties purchasing such software from CUSTOMER. 
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LIMITED WARRANTY 

For a period of 90 days from the date of delivery, Radio Shack warrants to the 
original purchaser that the computer hardware unit shall be free from manufac- 
turing defects. This warranty is only applicable to the original purchaser who 
purchased the unit from Radio Shack company-owned retail outlets or duly 
authorized Radio Shack franchisees and dealers. This warranty is voided if the 
unit is sold or transferred by purchaser to a third party. This warranty shall be 
void if this unit's case or cabinet is opened, if the unit has been subjected to 
improper or abnormal use, or if the unit is altered or modified. If a defect occurs 
during the warranty period, the unit must be returned to a Radio Shack store, 
franchisee, or dealer for repair, along with the sales ticket or lease agreement. 
Purchaser's sole and exclusive remedy in the event of defect is limited to the 
correction of the defect by adjustment, repair, replacement, or complete 
refund at Radio Shack's election and sole expense. Radio Shack shall have no 
obligation to replace or repair expendable items. 

Any statements made by Radio Shack and its employees, including but not 
limited to, statements regarding capacity, suitability for use, or performance of 
the unit shall not be deemed a warranty or representation by Radio Shack for 
any purpose, nor give rise to any liability or obligation of Radio Shack. 

EXCEPT AS SPECIFICALLY PROVIDED IN THIS WARRANTY OR IN THE 
RADIO SHACK COMPUTER SALES AGREEMENT, THERE ARE NO 
OTHER WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT 
LIMITED TO, ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR 
FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL RADIO 
SHACK BE LIABLE FOR LOSS OF PROFITS OR BENEFITS, INDIRECT, 
SPECIAL, CONSEQUENTIAL OR OTHER SIMILAR DAMAGES ARISING 
OUT OF ANY BREACH OF THIS WARRANTY OR OTHERWISE. 
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